Incident brief
GET STACKED DIAGNOSTICS outside a handler
GET STACKED DIAGNOSTICS reads details of the exception currently being handled, so it is only valid inside an EXCEPTION handler; using it elsewhere raises this diagnostics exception.
In 10 seconds
- What
- GET STACKED DIAGNOSTICS outside a handler
- What triggers it
- Call GET STACKED DIAGNOSTICS in PL/pgSQL code that is not inside an EXCEPTION handler.
- The fix
- Move the GET STACKED DIAGNOSTICS into an EXCEPTION ... handler block.
- Proof
- Reproduced on PostgreSQL 18.4 → A DO block reproduces SQLSTATE 0Z002; GET STACKED DIAGNOSTICS outside a handler is rejected, naming the statement in the CONTEXT.
The fix
What to do right now
The immediate, application-level response to this error.
- Move the GET STACKED DIAGNOSTICS into an EXCEPTION ... handler block.
- Use GET CURRENT DIAGNOSTICS (not STACKED) if you need diagnostics outside a handler.
-- Read stacked diagnostics only inside an EXCEPTION handler.
DO $$ DECLARE msg text; BEGIN BEGIN RAISE EXCEPTION 'boom'; EXCEPTION WHEN others THEN GET STACKED DIAGNOSTICS msg = MESSAGE_TEXT; RAISE NOTICE 'caught: %', msg; END; END $$;Diagnose
See it live on the server
Run these against the affected instance to confirm the diagnosis before you act.
Standard triage — not specific to this error
These are canonical PostgreSQL system-catalog queries, shown as SQL to run. No sample output is attached because this is general triage, not a captured lab transcript.This SQLSTATE does not have an error-specific live snapshot yet. These are the canonical system-catalog queries you run against the affected server to see the problem in real time — standard triage, not a reproduced transcript.
What is running right now
Active backends, how long each has been running, and what it is waiting on.
SELECT pid,
state,
wait_event_type,
wait_event,
now() - query_start AS running_for,
left(query, 80) AS query
FROM pg_stat_activity
WHERE state <> 'idle'
AND pid <> pg_backend_pid()
ORDER BY running_for DESC NULLS LAST;Who is blocking whom
Turn raw blocking PIDs into the actual queries on both sides of the wait.
SELECT blocked.pid AS blocked_pid,
blocked.query AS blocked_query,
blocking.pid AS blocking_pid,
blocking.query AS blocking_query
FROM pg_stat_activity AS blocked
JOIN LATERAL unnest(pg_blocking_pids(blocked.pid)) AS b(pid) ON true
JOIN pg_stat_activity AS blocking ON blocking.pid = b.pid
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;Locks that are still waiting
Every lock a backend has requested but not yet been granted.
SELECT l.pid,
l.locktype,
l.mode,
l.granted,
COALESCE(c.relname, l.transactionid::text) AS object
FROM pg_locks l
LEFT JOIN pg_class c ON c.oid = l.relation
WHERE NOT l.granted
ORDER BY l.pid;Why it happens
What PostgreSQL is telling you
The mechanism behind the error, grounded in the official manual — not paraphrased.
PostgreSQL 18 Documentation — Appendix A. PostgreSQL Error Codes (Table A.1, Class 0Z — Diagnostics Exception)
0Z002 → stacked_diagnostics_accessed_without_active_handlerRead the full section on postgresql.org →
Reading stacked diagnostics with no active handler
GET STACKED DIAGNOSTICS only works while an exception is being handled, so calling it outside a handler raises 'cannot be used outside an exception handler'.The session continues normally
The failing statement ran outside a transaction block, so nothing was left in a bad state — the next statement in the same connection runs normally.Reproduce & verify
A real, single-session PostgreSQL reproduction
A literal transcript of SQL run against a live PostgreSQL instance in an isolated lab — the commands below are exactly what was executed.
- 1Call GET STACKED DIAGNOSTICS in PL/pgSQL code that is not inside an EXCEPTION handler.
- 2PL/pgSQL finds there is no active exception to read diagnostics from.
- 3The statement aborts with SQLSTATE 0Z002.
Error-inspection code called GET STACKED DIAGNOSTICS in the main body instead of inside the EXCEPTION block, so there was no exception to read.
-- The error is self-contained in one statement; no schema is required.
SELECT 'no schema needed' AS setup_note;DO $$ DECLARE msg text; BEGIN GET STACKED DIAGNOSTICS msg = MESSAGE_TEXT; END $$;SELECT 'ok' AS session_after_error;What PostgreSQL actually returned
setup_note
------------------
no schema needed
(1 row)ERROR: GET STACKED DIAGNOSTICS cannot be used outside an exception handler
CONTEXT: PL/pgSQL function inline_code_block line 1 at GET STACKED DIAGNOSTICS session_after_error
---------------------
ok
(1 row)The diagnostics read succeeds once it runs inside an EXCEPTION handler.
We wrap the logic in a BEGIN ... EXCEPTION block so a real exception is active when we read its diagnostics.
Without this
Before: reading diagnostics with no handler aborts
With this, tested
After: the handler makes diagnostics available
What Pro unlocks here
- The exact prevention SQL — copy-paste ready
- Raw psql output captured from the Docker lab
- A senior-DBA action list to take it further
- Live monitoring queries to catch it in production
- The deeper audit: fix-that-fails counterexample, GUC before/after, server-log evidence
Related & next steps
Follow the thread
Everything this error touches — jump straight to the sibling error, term, runbook, or parameter.
Verification
- Last verified
- 2026-07-24 (isolated lab, PostgreSQL 18.4)
- Reviewed by
- Verified against PostgreSQL 18.4 in an isolated lab environment
- Audit status
- reviewed