// PostgreSQL error reference

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
Error message
terminating connection due to idle-in-transaction timeout

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 BEGIN and COMMIT.
  • 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

  1. 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;
  2. Do slow non-database work before opening the transaction or after committing it, and always commit or roll back in a finally block.

  3. 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

More invalid transaction state errors

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.

// fewer errors, faster fixes

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.