PostgreSQL Error 08006: Connection Failure

PostgreSQL error 08006 (Connection Failure) explained: what it means, why it happens, and how to fix it — with copy-paste code examples.

SQLSTATE 08006 PostgreSQL Last verified 2026-08-19

Quick Answer

Add connection retry with backoff in the client. If that does not apply, enable TCP keepalives / lower tcp_keepalives_interval to detect dead connections — the full checklist is below.

Error Code

SQLSTATE: 08006
Official name: Connection Failure
Service: PostgreSQL

What does this error mean?

The connection to the server failed during the operation.

Common Causes

How to Fix

  1. Add connection retry with backoff in the client
  2. Enable TCP keepalives / lower tcp_keepalives_interval to detect dead connections
  3. Use a pooler (PgBouncer) to manage connection lifecycle
  4. Verify max_connections and server health in the logs

Code Examples

Tune keepalives to detect dead connections sql 
ALTER SYSTEM SET tcp_keepalives_idle = 60;
ALTER SYSTEM SET tcp_keepalives_interval = 10;
ALTER SYSTEM SET tcp_keepalives_count = 5;
SELECT pg_reload_conf();

Short keepalive probes surface dead connections quickly so clients get 08006 and can retry instead of hanging.

Framework-Specific Fixes

sqlalchemy

Use pool_pre_ping=True so dead connections are detected and replaced before use.

engine = create_engine(url, pool_pre_ping=True, pool_recycle=1800)
django

Set CONN_MAX_AGE and enable persistent connections with health checks.

DATABASES = {'default': {'CONN_MAX_AGE': 60, 'CONN_HEALTH_CHECKS': True}}
supabase

Use the connection pooler URL (port 6543) for serverless clients to avoid 08006 on cold connections.

postgresql://postgres.[ref]:[key]@aws-0-[region].pooler.supabase.com:6543/postgres

You Might Also Like

08001 Sqlclient Unable to Establish Sqlconnection The SQL client could not establish a connection to the SQL server. 08003 Connection Does Not Exist The operation was attempted on a connection that does not exist (already closed or never opened).

Frequently Asked Questions

Why am I seeing PostgreSQL error 08006?

Most often this happens when network interruption between client and server mid-transaction, or when server restart or crash during a long-running query.

How do I fix PostgreSQL error 08006?

Add connection retry with backoff in the client.

Which frameworks have documented fixes for error 08006?

This page documents fixes for: sqlalchemy, django, supabase.

Official Sources

This page is based on the official PostgreSQL documentation linked below and adds practical troubleshooting guidance on top.