Sqlclient Unable To Establish Sqlconnection — SQLSTATE 08001

SQLSTATE 08001 condition sqlclient_unable_to_establish_sqlconnection class 08 — Connection Exception severity ERROR
Reproduced & verified on PostgreSQL 14.23, 15.18, 16.14, 17.10 and 18.4 — identical message on every version.
Last reviewed 29 May 2025 · Reproduced live with the SQL on this page.

! Symptoms Free

The client could not establish a connection — typically the server is unreachable or not listening for this client.

  • The error is written to the server log and returned to the client carrying SQLSTATE 08001.
  • Any driver (libpq, JDBC, psycopg, npgsql, pgx) surfaces this code in its error object so you can branch on it programmatically.
  • PL/pgSQL can trap it by name: EXCEPTION WHEN sqlclient_unable_to_establish_sqlconnection THEN.

1 Environment & reproduce Free

Severity: ERROR  |  PostgreSQL versions: 12, 13, 14, 15, 16, 17

Commonly coincides with restarts, failover, maintenance, or network events; check server uptime and the log around the timestamp.

? Root cause Free

The driver failed before authentication completed. PostgreSQL (or the network) refused or never answered the connection attempt.

Common causes:

  • Wrong host, port, or database name in the connection string.
  • listen_addresses does not include the client's network interface.
  • The server is not started, or a firewall blocks port 5432.
  • TLS is required but the client is not configured for it.

3 Recovery & verify Free

Steps to resolve 08001:

  1. Verify host, port, and database name in the connection string.
  2. Set listen_addresses = '*' (or the correct interface) in postgresql.conf and restart.
  3. Add a matching pg_hba.conf entry for the client IP, database, and role.
  4. Test raw connectivity: psql "host=... port=5432 user=... dbname=..." and pg_isready.
  5. Check firewalls/security groups and the required sslmode.

Reference: PostgreSQL error codes — Class 08 (Connection Exception).