EC
08001
PostgreSQLFATALNotableConnection ExceptionMEDIUM confidence

could not connect to server

What this means

The client was unable to establish a TCP connection to the Postgres server at all. Unlike 08006 (which is a drop of an established connection), 08001 means the initial TCP handshake or the Postgres startup protocol never completed.

Why it happens
  1. 1Postgres is not running on the target host and port
  2. 2Firewall or security group blocks inbound TCP on the Postgres port (default 5432)
  3. 3Incorrect hostname or IP address in the connection string
  4. 4Postgres is listening on a different port or only on localhost (127.0.0.1) when a remote connection is attempted
  5. 5max_connections reached and all connection slots are in use
How to reproduce

A client attempts to connect to a Postgres host that is unreachable.

trigger — this will error
trigger — this will error
-- From psql:
-- psql -h 10.0.0.1 -p 5432 -U postgres mydb
-- (when the server is not running or unreachable)

expected output

psql: error: connection to server at "10.0.0.1", port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

Fix 1

Verify Postgres is running and listening on the correct address

WHEN When the server may be down or misconfigured.

Verify Postgres is running and listening on the correct address
-- On the server OS (not SQL):
-- pg_lsclusters (Debian/Ubuntu)
-- systemctl status postgresql

-- Check listening addresses in postgresql.conf:
SHOW listen_addresses;
SHOW port;

-- Verify from pg_hba.conf that the host is allowed.

Why this works

Postgres listens on the addresses specified by listen_addresses. The default is localhost, which refuses all external TCP connections. Changing listen_addresses to * or the server's external IP and reloading (or restarting) causes the postmaster to bind to the new address.

Fix 2

Check and open firewall rules

WHEN When the server is running but network access is blocked.

Check and open firewall rules
-- OS-level (not SQL); example for ufw:
-- ufw allow 5432/tcp

-- Cloud security group: add inbound rule for TCP port 5432
-- from the client IP range.

Why this works

The OS firewall (iptables/nftables) or cloud security group drops TCP SYN packets before they reach the Postgres listener. Opening port 5432 for the client IP allows the TCP handshake to complete.

What not to do

✕ Open port 5432 to 0.0.0.0/0 (all internet) to simplify connectivity

Exposes Postgres directly to the internet; credential brute-force and exploitation attempts will follow immediately.

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All PostgreSQL errors