How to fix FATAL: terminating connection due to idle_session_timeout in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 29, 2025· 335 views

PostgreSQL automatically closes idle sessions based on the idle_session_timeout parameter, typically set for interactive users. This error occurs when a session has been idle (not running queries) for longer than the configured timeout duration.

Quick fix

Fixes FATAL: terminating connection due to idle_session_timeout

SELECT name, setting FROM pg_settings WHERE name = 'idle_session_timeout';
  1. Check current idle_session_timeout setting
  2. Disable idle_session_timeout if not needed
  3. Set timeout only for specific interactive users
  4. Increase the timeout duration if needed
postgresql — error
SELECT name, setting FROM pg_settings WHERE name = 'idle_session_timeout';
FATAL: terminating connection due to idle_session_timeout

What this error means

The idle_session_timeout parameter controls the maximum amount of time a session can remain idle before PostgreSQL automatically terminates the connection. Introduced in PostgreSQL 14, this setting applies to any session that is idle when not in a transaction. When the timeout expires, PostgreSQL sends a FATAL error and closes the connection. Unlike idle_in_transaction_session_timeout, which only applies to sessions waiting inside a transaction, idle_session_timeout applies to all idle sessions regardless of transaction state.

Typical symptoms

  • Connection suddenly terminates while waiting for user input
  • Database tools or IDEs disconnect unexpectedly
  • Interactive sessions end abruptly without warning
  • Error appears in PostgreSQL logs with idle_session_timeout reference
  • Applications lose database connections during idle periods

Common causes

  1. idle_session_timeout parameter is set at the server level and the session exceeded the timeout duration
  2. Interactive user accounts have restrictive timeout settings configured
  3. Firewall, router, or network appliance is closing connections silently
  4. Connection pooler middleware is not configured to keep connections alive
  5. TCP keepalive settings are not configured on the server

How to fix "FATAL: terminating connection due to idle_session_timeout"

1Check current idle_session_timeout setting

First, verify what idle_session_timeout is set to on your PostgreSQL server:

sql
SELECT name, setting FROM pg_settings WHERE name = 'idle_session_timeout';

The result shows the timeout value in milliseconds. A value of 0 means the timeout is disabled. If the setting is non-zero, it's actively terminating idle sessions.

2Disable idle_session_timeout if not needed

If you don't need idle session timeout, disable it by setting it to 0:

sql
ALTER SYSTEM SET idle_session_timeout = 0;

Then reload the configuration:

sql
SELECT pg_reload_conf();

This disables the timeout globally. Verify the change took effect by running the pg_settings query again.

3Set timeout only for specific interactive users

Best practice: don't apply idle_session_timeout globally. Instead, set it only for interactive login accounts:

sql
ALTER ROLE interactive_user SET idle_session_timeout = 600000; -- 10 minutes

Avoid setting this for service or application accounts, as connection poolers and application frameworks may not handle unexpected disconnections gracefully.

4Increase the timeout duration if needed

If you need idle_session_timeout for interactive users, increase the duration to a reasonable value:

sql
ALTER ROLE interactive_user SET idle_session_timeout = 1800000; -- 30 minutes

Timeout values are in milliseconds. Common durations:
- 600000 = 10 minutes
- 1200000 = 20 minutes
- 1800000 = 30 minutes

Choose a value that matches your expected user behavior.

5Configure client-side connection timeout

Prevent frozen connections on the client side by adding a connection timeout to your connection string:

bash
postgresql://user:password@host:5432/database?connect_timeout=5

Or set the PGCONNECT_TIMEOUT environment variable:

bash
export PGCONNECT_TIMEOUT=5

This ensures clients don't hang indefinitely on network failures.

6Enable TCP keepalive for better connection stability

Configure TCP keepalive to detect and clean up dead connections:

sql
ALTER SYSTEM SET tcp_keepalives_idle = 120;      -- 2 minutes
ALTER SYSTEM SET tcp_keepalives_interval = 30;   -- 30 seconds
ALTER SYSTEM SET tcp_keepalives_count = 5;       -- 5 probes

Then reload:

sql
SELECT pg_reload_conf();

TCP keepalive helps detect network issues without relying on idle_session_timeout.

7Consider connection pooling for applications

If your application experiences frequent disconnections, use a connection pooler like PgBouncer to manage connections and reduce the impact of timeouts:

bash
sudo apt-get install pgbouncer

Configure PgBouncer in your connection pool to:
- Reuse connections across multiple application processes
- Implement connection pooling strategies (transaction or session mode)
- Handle reconnection logic automatically

This allows the pooler to manage timeouts while keeping application connections stable.

Advanced notes

idle_session_timeout applies to sessions when NOT in a transaction, making it less critical than idle_in_transaction_session_timeout. However, unlike an open transaction, an idle session imposes minimal server resource cost, so enabling this timeout is usually unnecessary unless managing interactive user behavior. Be cautious when setting idle_session_timeout on connections made through connection pooling middleware; unexpected connection closures can cause poolers to behave unpredictably. For production databases, prefer using idle_in_transaction_session_timeout (which terminates only transactions) rather than idle_session_timeout. PostgreSQL 14+ introduced idle_session_timeout; earlier versions only have idle_in_transaction_session_timeout. Consider using role-based settings to apply different timeouts to different user categories (interactive vs. service accounts). TCP keepalive is a complementary approach that doesn't require parameter changes and may be preferable in shared infrastructure environments.

Frequently asked questions

What does "FATAL: terminating connection due to idle_session_timeout" mean?
The idle_session_timeout parameter controls the maximum amount of time a session can remain idle before PostgreSQL automatically terminates the connection. Introduced in PostgreSQL 14, this setting applies to any session that is idle when not in a transaction. When the timeout expires, PostgreSQL sends a FATAL error and closes the connection.
How do I fix "FATAL: terminating connection due to idle_session_timeout"?
PostgreSQL automatically closes idle sessions based on the idle_session_timeout parameter, typically set for interactive users. This error occurs when a session has been idle (not running queries) for longer than the configured timeout duration.
What causes "FATAL: terminating connection due to idle_session_timeout"?
idle_session_timeout parameter is set at the server level and the session exceeded the timeout duration Interactive user accounts have restrictive timeout settings configured Firewall, router, or network appliance is closing connections silently
Is the "FATAL: terminating connection due to idle_session_timeout" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading