SQLSTATE 08006 ERROR Class 08: Connection Exception

connection_failure connection to server at “…”, port … failed — 08006

PostgreSQL error "connection to server at "…", port … failed" (SQLSTATE 08006): 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 connection attempt to the given host and port failed. The driver reports SQLSTATE 08006 (connection_failure) with details about why.

  • The message names the host and port that failed.
  • Accompanied by a reason (refused, timed out, no route, etc.).
  • A general connection-failure wrapper message.

What the server log shows

connection to server at "db.example.com" (203.0.113.10), port 5432 failed: Connection timed out

Why PostgreSQL raises this — what the manual says

Section 32.1 Database Connection Control Functions (PQpingParams):

“This might indicate that the server is not running, or that there is something wrong with the given connection parameters (for example, wrong port number), or that there is a network connectivity problem (for example, a firewall blocking the connection request).”

When libpq cannot establish a session, it reports 08006 along with the target host/port and the OS-level reason (refused, timeout, unreachable). The specific reason guides the fix.

Common causes

  • Server down or not listening on that address/port.
  • Network issues: timeouts, no route, DNS resolution failure.
  • Firewall/security-group rules blocking the connection.

How to fix it

  1. Read the appended reason and address it (refused vs timed out differ).
  2. Verify host/port, DNS, and that the server listens on that address.
  3. Check firewalls, security groups, and network routes.

Related & next steps

Reference: PostgreSQL 18 Section 34.1 “Connection Control”.

Was this helpful?