// PostgreSQL error reference

PostgreSQL 08001: unable to establish connection

The client couldn't open a connection to the server at all: nothing listening on that host and port, a firewall, DNS, or a timeout.

SQLSTATE
08001
Name
sqlclient_unable_to_establish_sqlconnection
Category
Connection Exception
Error message
connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

What it means

08001 is a client-side SQLSTATE: drivers such as PgJDBC and Npgsql report it when they can't establish a connection, and libpq-based tools print messages like the one above. The server never saw a login attempt, so the problem is the network path or the server not listening, not credentials.

The operating-system error at the end says which: Connection refused means the host answered but nothing listens on that port; timeout expired or Operation timed out usually means a firewall dropped the packets; could not translate host name is DNS.

Common causes

  • The PostgreSQL server isn't running, or is listening on another port.
  • listen_addresses is localhost (the default), so the server only accepts local connections.
  • A firewall, security group or Docker port mapping blocks port 5432.
  • Wrong host name, or a host name that doesn't resolve from the client.
  • Connecting to localhost from inside a container, which refers to the container itself.

How to fix it

  1. On the server, check that PostgreSQL is running and which addresses and port it listens on.

    SHOW listen_addresses;
    SHOW port;
  2. Allow network connections: set listen_addresses = '*' (or the server's address) in postgresql.conf and restart, then add a pg_hba.conf rule for the clients.

  3. Test the network path from the client, for example pg_isready -h db.example.com -p 5432, and open the port in the firewall or security group.

  4. From a container, connect to the database container's service name or the host's address instead of localhost.

Related errors

The code and message text are from the PostgreSQL documentation, Appendix A: PostgreSQL Error Codes. Browse the full PostgreSQL error list or search every database error.

// fewer errors, faster fixes

Work on PostgreSQL in SQLly

A native SQL client for macOS, Windows and Linux with schema-aware IntelliSense, guardrails for risky statements and clear error messages, for PostgreSQL and the other databases you use.