25P03ERRORTier 2 — Caution✅ HIGH confidence

idle in transaction session timeout

Category: Invalid Transaction StateVersions: Postgres 9.6+

What this means

SQLSTATE 25P03 is raised when a session has been idle inside a transaction for longer than the idle_in_transaction_session_timeout setting. Postgres terminates the session to reclaim resources held by the open transaction.

Why it happens

1An application opened a transaction (BEGIN) and then stopped sending queries, holding the transaction open beyond idle_in_transaction_session_timeout
2Long-running application pause, network stall, or debugging session inside a BEGIN block

How to reproduce

Application holds an open transaction for too long without activity.

trigger — this will ERROR

-- In postgresql.conf:
-- idle_in_transaction_session_timeout = 30s

FATAL: terminating connection due to idle-in-transaction timeout

Fix 1: Keep transactions short and release them promptly

Always in production.

fix

Why this works

Complete transactions quickly — do not hold open transactions across user-facing latency, network calls, or sleep() delays. Commit or rollback immediately after the last query.

Fix 2: Increase idle_in_transaction_session_timeout if legitimate long transactions are needed

When a known long-running transaction process is expected.

fix

SET idle_in_transaction_session_timeout = '5min';

Why this works

Raising the timeout gives the session more time, but should be accompanied by ensuring the transaction eventually completes.

What not to do

✗

Set idle_in_transaction_session_timeout = 0 (disabled)

Why it's wrong: Disabling it allows runaway idle transactions to hold locks indefinitely, blocking other sessions.

Version notes

Postgres 9.6+idle_in_transaction_session_timeout parameter introduced in Postgres 9.6.

Sources

📚 Official docs: https://www.postgresql.org/docs/current/errcodes-appendix.html

📚 Feature docs: https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT

🔧 Source ref: Class 25 — Invalid Transaction State (Postgres-specific)

Confidence assessment

✅ HIGH confidence

Postgres-specific since 9.6. Commonly seen in production when applications hold idle transactions.