PostgreSQL 25P03: idle-in-transaction session timeout
The session sat inside an open transaction doing nothing for longer than idle_in_transaction_session_timeout, so the server closed it.
- SQLSTATE
25P03- Name
idle_in_transaction_session_timeout- Category
- Invalid Transaction State
What it means
A session that has started a transaction and then goes quiet is idle in transaction. It still holds its locks and keeps old row versions from being vacuumed. idle_in_transaction_session_timeout makes the server end such sessions after a time limit; when it fires, the client gets this FATAL error and the connection is closed, rolling the transaction back.
The usual root cause is application code that opens a transaction and then waits on something else, such as a network call or user input, before committing.
Common causes
- Code that does slow work (HTTP calls, file processing) between
BEGINandCOMMIT. - A client or GUI with autocommit off, left open after a
SELECT, so a transaction stays open. - An exception path that never commits or rolls back, leaving the pooled connection idle in a transaction.
How to fix it
-
Find sessions idle in a transaction and how long they have been idle.
SELECT pid, usename, application_name, now() - state_change AS idle_for, query FROM pg_stat_activity WHERE state = 'idle in transaction' ORDER BY idle_for DESC;
-
Do slow non-database work before opening the transaction or after committing it, and always commit or roll back in a
finallyblock. -
Keep the timeout as a safety net; set it per role or database if some jobs legitimately need longer.
ALTER ROLE app SET idle_in_transaction_session_timeout = '5min';
Related errors
57P01terminating connection due to administrator53300too many connections55P03lock not available08006connection failure
More invalid transaction state errors
25001cannot run inside a transaction block25006read-only SQL transaction25P02current transaction is aborted
The code and message text are from the PostgreSQL documentation, Appendix A: PostgreSQL Error Codes. Browse the full PostgreSQL error list or search every database error.
Work on PostgreSQL in SQLly
A native SQL client for macOS, Windows and Linux with schema-aware IntelliSense, guardrails for risky statements and clear error messages, for PostgreSQL and the other databases you use.