HA & DR

ORA-04068 After a Deploy: The Retry Works. The Package State Is Gone.

· 12 min read

The release went fine. Every script ran, every package compiled, the smoke test passed. A minute later the application log fills with this:

ORA-04068: existing state of packages has been discarded
ORA-04061: existing state of package body "APP.PRICING" has been invalidated
ORA-04065: not executed, altered or dropped package body "APP.PRICING"

Then it stops. A few dozen errors, one per connection, and nothing after. Someone opens an incident, someone else suggests rolling back, and by the time anyone looks, the errors are gone.

The package isn’t broken. It holds state, the deploy threw that state away, and Oracle told each session about it the first time it came back. The error is the visible part. The quieter part is that the retry works with the state reset, and not only for the package you deployed.

This post covers what the error means, which packages and which changes raise it (two of them look harmless), what a connection pool sees, and how to deploy PL/SQL without it. It ends with a lab that proves each step on Oracle Database Free 26ai.

What the error means

Each session that uses a package gets its own copy of the package’s variables: its package state. A counter, a cached config row, a flag set at login, a lookup table loaded once. Oracle’s PL/SQL Language Reference calls a package stateful if it declares at least one variable, constant or cursor, and stateless otherwise. That state lives for the whole session.

Except when the package body is recompiled. A deploy (CREATE OR REPLACE PACKAGE BODY), an explicit ALTER PACKAGE ... COMPILE, or an automatic recompile after something the package depends on changed. The state in every session was built by the old code, so it can’t be kept. The next time a session calls the package, Oracle discards that state and raises ORA-04068. The two errors under it say which package, and why.

In the lab, a session called a package with one variable, a call counter, twice: 1, 2. The deploy replaced the package body. The session’s next call failed with exactly the three errors above. The call after that worked, ran the new code, and returned 1. The counter started again from its initial value.

Two things the error does not do, both checked in the lab:

  • It doesn’t roll back the session’s transaction. The session had an uncommitted insert before the deploy. It was still there after the error.
  • It doesn’t come back. It’s raised once per session per recompile. The next call re-creates the package state from scratch and runs.

It’s the state, not the change

Whether a deploy raises ORA-04068 doesn’t depend on how big the change is. It depends on whether the package holds state when it’s recompiled. In the lab, a session used each package, one change was deployed, and the session called the package again:

PackageChange deployedNext call
no package variablesnew bodyno error, new code at once
no package variablesnew spec (a function added) and bodyno error, new code at once
only a literal constant (c_rate CONSTANT NUMBER := 5)new bodyno error, new code at once
a constant set at load (c_loaded CONSTANT DATE := SYSDATE)new bodyORA-04068
one variableALTER PACKAGE ... COMPILE BODY, no code changeORA-04068
a %ROWTYPE variable on ORDERSALTER TABLE orders ADD a columnORA-04068
a variable, but the code names its columnsthe same ADD columnno error

Three of these surprise people.

A constant isn’t always a constant. Oracle treats a package as stateless if its state can’t change for the life of a session, which is the case when every item is a compile-time constant. A literal is one. SYSDATE isn’t: its value is set when the session first uses the package. So c_loaded CONSTANT DATE := SYSDATE makes the package stateful, and the deploy that changed nothing else raised ORA-04068.

A recompile with no change is enough. ALTER PACKAGE pricing COMPILE BODY, with the exact same code, raised it. So does any script that recompiles invalid objects after a release, for every stateful package it touches.

DDL on a table can do it, with no PL/SQL deploy at all. A package body with a variable declared as orders%ROWTYPE depends on the table’s column list. ALTER TABLE orders ADD a column invalidated it, and the next call raised ORA-04068. A package that used the same table but named its columns stayed VALID and didn’t raise it. So the ADD COLUMN that waited politely for its lock can still throw errors at the application once it runs.

The other direction also held. A package with no variables switched to the new code silently, even when its spec changed. In a hand run, a standalone function that called that package was invalidated by the spec change, recompiled itself on its next call, and also raised nothing.

It resets packages the release didn’t touch

The documentation has one more sentence that’s easy to read past: all of a session’s package states can be lost if any of its instantiated packages is invalidated and revalidated.

The lab tested it. A session used two packages, PRICING and AUDIT_CTX, each with its own counter. The release recompiled only AUDIT_CTX.

PRICING   (not redeployed): 1, 2, 3        then, after AUDIT_CTX's error: 1
AUDIT_CTX (recompiled):     1, ORA-04068, 1

PRICING kept counting until the session called AUDIT_CTX and got ORA-04068. After that, PRICING was back to 1 too. Its code hadn’t changed and nobody had deployed it, but its state was gone. (In a hand run, recompiling a package without variables didn’t do this: the session’s other packages kept their state.)

So “we only changed one package” doesn’t limit the damage. Any session that hits ORA-04068 for any package starts again with every package’s state at its initial value. If one of them caches a user’s permissions, a tenant ID or a feature flag, the retry that “fixed” the error runs with the defaults.

A recompile of a stateful package doesn't fail the deploy. It fails the next call in every session that had used the package, once, and that session's retry starts with every package's state at its initial value. Packages without state, SERIALLY_REUSABLE packages and edition-based redefinition avoid the error.

What a connection pool sees

A connection pool turns one recompile into a burst. Each pooled connection is a session, so each one that had used the package raises ORA-04068 once.

The lab opened 8 sessions; 6 of them called the package, 2 didn’t. After one deploy, every session called it twice:

first round after the deploy:  6 of 8 calls failed with ORA-04068
second round:                  0 of 8

The 2 sessions that had never used the package got the new code with no error. The 6 that had used it failed once each, even though the call they made after the deploy only read a version string and never touched the variable. What’s discarded is the session’s copy of the package, not one variable.

That’s the shape to recognize in a log: a burst right after a deploy, about one error per connection, then nothing. A pool of 200 connections gives you up to 200 errors and 200 resets of the package state. Unless your code retries, each of those errors is a failed user request.

Find the stateful packages before you deploy

There’s no column in the data dictionary that says “this package is stateful”, but PL/Scope can tell you. Compile with identifier collection on, then list the declarations at package level:

ALTER SESSION SET plscope_settings = 'IDENTIFIERS:ALL';
ALTER PACKAGE pricing COMPILE;          -- for each package you want to check

SELECT object_name, object_type, name, type
FROM   user_identifiers
WHERE  object_type IN ('PACKAGE', 'PACKAGE BODY')
AND    usage = 'DECLARATION'
AND    type IN ('VARIABLE', 'CONSTANT', 'CURSOR')
AND    usage_context_id = 1               -- declared at package level, not inside a subprogram
ORDER  BY object_name, object_type;

In a hand run on 26ai it listed the counter variable, a package-level cursor, and both constants. It didn’t list the packages without package-level declarations. Check the CONSTANT rows by eye: a literal (:= 5) is stateless, anything else (:= SYSDATE, a function call) isn’t. Note that ALTER PACKAGE ... COMPILE is itself a recompile, so run this on a test database, not under a live application.

Deploy without it

There are four ways to deal with it. They’re not equal.

1. Keep state out of packages. A package without variables has nothing to discard. In the lab it took the new code with no error every time, spec change included. If a value must survive across calls, keep it somewhere a recompile doesn’t touch: a table, or an application context (SYS_CONTEXT), which belongs to the session rather than to a package. In a hand run, a tenant ID set in an application context was still there after ORA-04068 had reset the package counter in the same session. This is the real fix, and it means changing the code.

2. Retry once in the application. The second call works, so catching ORA-04068 and retrying the call makes the burst invisible to users. It’s cheap, and many teams do it. But the retry runs with every package’s state reset, including packages the deploy didn’t touch. Only retry if the code re-creates any state it needs, for example by re-running its login initialization.

3. PRAGMA SERIALLY_REUSABLE. A serially reusable package keeps its state only for the duration of one server call. In the lab, the deploy raised no error and the very next call ran the new code. The cost is in the name: the counter was 1 on every call, before and after the deploy, because nothing survives between calls. And a serially reusable package can’t be called from SQL at all: SELECT pricing.version FROM dual failed with ORA-06534: Cannot access Serially Reusable package. It suits packages that only use their variables within one call. It isn’t a switch you can turn on for a package that relies on its state.

4. Edition-based redefinition (EBR). Editions let two versions of the same package exist at once. Each session sees the version in its own edition. The release is compiled in a new edition while running sessions keep using the old one:

-- once, as a DBA: enable editions for the schema owner (this can't be undone)
ALTER USER app ENABLE EDITIONS;

-- per release
CREATE EDITION rel2;
GRANT USE ON EDITION rel2 TO app;

-- the deploy, in a session switched to the new edition
ALTER SESSION SET EDITION = rel2;
CREATE OR REPLACE PACKAGE BODY pricing AS ... END;

-- when you're ready for new connections to get the release
ALTER DATABASE DEFAULT EDITION = rel2;

In the lab, a session in the old edition (ORA$BASE) called the package before and after the new body was compiled in REL2: 1, 2, 3. No error, no reset, still the old code. A new session also got the old code until ALTER DATABASE DEFAULT EDITION = REL2; after that, new sessions got the new code. A connection pool moves to the release as its connections are replaced, and none of them sees ORA-04068 on the way.

EBR is in every edition of the database, Free included. The catch is preparation: ENABLE EDITIONS is one-way, and tables aren’t editioned, so changes to table structure need editioning views and crossedition triggers to fully avoid downtime. For PL/SQL-only releases, it does exactly what this error needs.

Prove it

The lab runs Oracle Database Free in a container. Each “user” session is a SQL*Plus session that calls the package, waits for the deploy, then calls it again:

drill    case                                                 result
error    package body replaced under a live session           ORA-04068 / 04061 / 04065 once; the retry works,
                                                              counter back to 1; uncommitted insert kept
collat   only AUDIT_CTX recompiled, session also uses PRICING PRICING reset to 1 too, after AUDIT_CTX's error
which    no variables (new body; new spec)                    no error, new code
         a literal constant                                   no error, new code
         CONSTANT DATE := SYSDATE                             ORA-04068
         ALTER PACKAGE ... COMPILE BODY, no code change       ORA-04068
         %ROWTYPE variable, then ALTER TABLE ... ADD          ORA-04068 (named columns: no error)
pool     8 sessions, 6 had used it, one deploy                6 errors, then 0
serial   PRAGMA SERIALLY_REUSABLE                             no error, new code at once; counter always 1;
                                                              ORA-06534 from SQL
edition  new body compiled in edition REL2                    live session: no error, 1, 2, 3 on the old code;
                                                              new sessions: new code after the default switch

Don’t take my word for it — run it. The package-state lab asserts every row: the three-error stack and the counter starting again at 1 after the retry, with the uncommitted insert still there; the untouched package reset by another package’s error; which packages and changes raise it and which don’t; exactly 6 errors from the 6 pooled sessions that had used the package and none on the second round; the serially reusable package’s missing error, missing state and ORA-06534; and the live session in the old edition counting on with no error. If any of that doesn’t reproduce, the run fails. Proven on every CI push.

What teams get wrong

  • Rolling back a good release. The burst looks like a broken deploy. It’s one error per connection, and it’s over by the time anyone looks. Rolling back is another recompile, and another burst.
  • Assuming the retry is clean. It runs, but with every package’s state reset, including packages the release didn’t touch.
  • Thinking CONSTANT means stateless. Only compile-time constants do. := SYSDATE makes the package stateful.
  • Recompiling “just to be safe”. A no-change COMPILE BODY raises it for every session that had used the package.
  • Forgetting that table DDL recompiles PL/SQL. An ADD column under a %ROWTYPE package variable raises it, with no PL/SQL in the release.
  • Adding SERIALLY_REUSABLE to make the error go away. It does, along with the state, and SQL can no longer call the package.

Frequently asked questions

What does ORA-04068 existing state of packages has been discarded mean?

A session had used a PL/SQL package that holds state (package-level variables, cursors, or constants that aren't compile-time constants), and the package body was recompiled since: by a deploy, an ALTER PACKAGE ... COMPILE, or an automatic recompile after a dependency changed. Oracle can't keep state built by the old code, so on the session's next call it discards the state and raises ORA-04068, with ORA-04061 and ORA-04065 naming the package. The next call re-creates the state from scratch and works.

Why does ORA-04068 go away when I run the call again?

Because the error is raised once per session per recompile. The failing call discards the session's package state; the next call re-instantiates the package with its initial values and runs the new code. In the companion lab the retry worked every time, but a counter the session had built up was back to 1. Any value the package had cached for the session is gone.

How do I prevent ORA-04068 after deploying a PL/SQL package?

Keep state out of packages you redeploy (a package with no variables, or only literal constants, switched to new code with no error in the companion lab), retry the call once in the application if your code can re-create the state it needs, use PRAGMA SERIALLY_REUSABLE for packages that only need state within one call, or deploy with edition-based redefinition so running sessions keep the old version. In the lab, a session in the old edition saw no error and kept its state while the new code was compiled in a new edition.

Can ORA-04068 happen for a package I didn't change?

Yes, in two ways. A package is recompiled automatically when something it depends on changes: in the companion lab, ALTER TABLE ADD COLUMN invalidated a package with a %ROWTYPE variable on that table, and the next call raised ORA-04068. And once a session gets ORA-04068 for any package, it loses the state of all its packages: in the lab, a package the release never touched was reset to its initial value after another package's error.

Does PRAGMA SERIALLY_REUSABLE fix ORA-04068?

It avoids it: in the companion lab, a serially reusable package raised no error after its body was replaced, and the next call ran the new code. But its state lasts only for one server call, so a counter was 1 on every call, and it can't be called from SQL: a SELECT that called it failed with ORA-06534. Use it for packages that don't rely on state between calls.

Does a package constant cause ORA-04068?

Only if it isn't a compile-time constant. Oracle treats a package whose items are all compile-time constants as stateless, and a literal (CONSTANT NUMBER := 5) is one: in the companion lab that package switched to new code with no error. A constant set from SYSDATE or a function call gets its value at run time, so the package is stateful, and in the lab it raised ORA-04068 after a deploy.

ORA-04068 after a deploy isn’t a failed release. It’s every session that had used a stateful package finding out that its state is gone, once, and starting again with all of its package state at the initial values. Know which of your packages hold state, keep it out of the ones you redeploy, and when you can’t, compile the release in a new edition so the live sessions never notice. Then prove it with the package-state lab, where one deploy fails 6 of 8 pooled connections once and resets a package nobody deployed.

Have a question or some feedback?

I write here in a personal capacity and enjoy comparing notes with other Oracle folks. Say hello.

Get in touch