SQLSTATE 25P03 FATAL Class 25: Invalid Transaction State

idle_in_transaction_session_timeout terminating connection due to idle-in-transaction timeout — 25P03

PostgreSQL error "terminating connection due to idle-in-transaction timeout" (SQLSTATE 25P03): what it means, common causes, and how to fix it.

PG 12, 13, 14, 15, 16, 17, 18 Official docs
Last reviewed May 2025 Grounded in source

Diagnostic Queries

Symptoms

A session held a transaction open and idle longer than idle_in_transaction_session_timeout, so the server terminated it. PostgreSQL raises SQLSTATE 25P03 (idle_in_transaction_session_timeout).

  • The connection is dropped, not just the statement.
  • Targets sessions stuck in idle in transaction state.
  • Protects against locks and bloat held by abandoned transactions.

What the server log shows

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

Why PostgreSQL raises this — what the manual says

Section 19.11.1 Statement Behavior (idle_in_transaction_session_timeout):

“Terminate any session that has been idle (that is, waiting for a client query) within an open transaction for longer than the specified amount of time.”

An open transaction holds locks and pins old row versions, blocking vacuum and other sessions. When such a session stays idle past the configured timeout, the server terminates it (25P03) to release those resources.

Common causes

  • An application opened a transaction and stalled (waiting on external work).
  • A forgotten BEGIN with no matching commit/rollback.
  • A connection pool checking out a connection mid-transaction.

Relevant GUC parameters

Parameter Default Effect
idle_in_transaction_session_timeout 0 Terminate sessions idle in a transaction longer than this (0 = disabled).
transaction_timeout 0 Abort any transaction exceeding this total duration (PG17+).

How to fix it

  1. Commit/rollback promptly; do not hold transactions open across external I/O.
  2. Make the app reconnect and retry after 25P03.
  3. Tune the timeout to balance safety against legitimate long transactions.

Related & next steps

Reference: PostgreSQL 18 Section 20.10 “Statement Behavior”.

Was this helpful?