25P03 — idle_in_transaction_session_timeout

At a glance

25P03 is a FATAL session-termination condition. It fires when a session is waiting for the next client query inside an open transaction longer than the effective idle_in_transaction_session_timeout. The selected case uses 300 ms as a harness trigger, not as a production recommendation.

Meaning

This timeout protects the server from sessions that keep an open transaction while waiting for the client; it can retain locks and delay cleanup. It applies while the session is idle in the transaction, including the idle in transaction and idle in transaction (aborted) states, not while an active statement is running. statement_timeout cancels a statement, while transaction_timeout covers the total transaction lifetime on versions that support it. The selected run covers the non-aborted INTRANS case only.

Diagnosis

Before the session disappears, capture its effective SHOW idle_in_transaction_session_timeout (or the matching pg_settings row) on that timed session itself. A control connection’s SHOW or pg_settings describes the observer backend and cannot establish another session’s effective SET value. From the control connection, inspect pg_stat_activity fields such as pid, usename, application_name, client_addr, state, xact_start, state_change, query_start, and query for state IN ('idle in transaction', 'idle in transaction (aborted)'). If the state is already aborted, preserve the earlier root error and 25P02 as separate diagnostics; the selected run is the non-aborted INTRANS path. These identify the pool or application path and how long it has been idle; permissions can limit what an observer sees. Correlate the FATAL record by backend PID, SQLSTATE, error_severity = FATAL, and exact message. The selected psycopg/libpq stack surfaced 25P03 in the driver diagnostic and CSV; PG18 also supplied JSON. The original connection is closed, so its transaction status cannot be repaired with ROLLBACK.

Response

Treat the session as gone: discard it from the pool and reconnect before retrying idempotent work. Prevent recurrence by committing or rolling back before returning a connection to the pool, and by fixing the application path that leaves a transaction open. Do not lower this timeout to suppress the error; a shorter value makes termination more likely. Choose an effective value above legitimate idle periods, or set it to 0 only when the deployment deliberately accepts the lock and cleanup risk. When the server closes this session, it rolls back the open incomplete transaction before exiting; the dead connection cannot accept a later ROLLBACK. A known uncommitted transaction on this terminated session cannot be recovered through that connection. If a separate network failure occurred after a COMMIT may have been sent, reconcile the business result from a fresh connection before retrying; that uncertainty is not implied by every 25P03 FATAL.

FATAL message

The server source emits terminating connection due to idle-in-transaction timeout at FATAL severity; the original connection is terminated.

Observed diagnostics

18.6 (Homebrew) / latest: FATAL SQLSTATE 25P03; primary terminating connection due to idle-in-transaction timeout; backend PID 26447; original connection closed True; collector CSV 25P03; collector JSON 25P03; fresh probe 1. 10.21 (Debian 10.21-1.pgdg90+1) / pg10: FATAL SQLSTATE 25P03; primary terminating connection due to idle-in-transaction timeout; backend PID 81; original connection closed True; collector CSV 25P03; collector JSON not applicable; fresh probe 1.

Representative case

The SQL excerpt below is not a paste-all script: run the setting, PID, and BEGIN on a test connection, then stop sending it queries while a separate observer or log collector waits for FATAL; after the old connection is terminated, open a fresh owner connection for the final probe. The runner reads these statements from the shared registry; complete assertions, collector correlation, environment, and cleanup are in case export.

-- set_timeout
SET idle_in_transaction_session_timeout = '300ms';
-- backend_pid
SELECT pg_backend_pid();
-- begin
BEGIN;
-- probe
SELECT 1;

The SQLSTATE, diagnostics, states, and repair assertions for this excerpt come from the shared registry (SHA-256 95fd079c8bca77c6e3ffc398e404a218e4f810e5fa36e30127cbc6470a6d6eb2); structured evidence.

Authored evidence IDs: identity, timeout-path, runtime. Selected runtime records: runtime.25P03-batch2c-latest-20260909.latest, runtime.25P03-batch2c-pg10-20260909.pg10.

Versions and limits

The selected 300 ms termination case passes on PostgreSQL 18.6 and 10.21. PG18 has CSV and JSON collector records; PG10 has CSV only under its configured logging target. Both fresh owner connections run SELECT 1 successfully. The timeout value is deployment-specific; the case does not prescribe it.

Related

25P04 transaction timeout, 25006 read-only SQL transaction, 57014 query canceled.

Sources

• src.errcodes.18.6 (SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba)
• src.calls.REL_18_6 — raw/calls/REL_18_6.jsonl (SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf)
• src.postgres.18.6 (SHA-256 9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061)
• src.config.18.6 (SHA-256 ffca322c15315ba670733d6b320f23cbba7374db0d18937298ffc07b58799ef6) · official documentation
• doc.monitoring.18.6 (SHA-256 06b147f8d966fe46821871703ffcee8a3449cc3f7de5b64b9177f48569fe96f6) · official monitoring documentation
• src.system_views.18.6 (SHA-256 418f4ae7472fe0742e6fbdc7a055581602c5131e082aa6f17e2c7269bf711972) · official pg_settings documentation
• doc.protocol.18.6 (SHA-256 745339e07ebbc2bb67d98b258e25772ada644ef26011e3cd6b3fcbb435235f89) · official protocol documentation