Troubleshoot PostgreSQL connection errors
Diagnose common failures in DNS, network, TLS, authentication, database, and connection capacity order
When failure happens before SQL execution, the client may not receive SQLSTATE. Preserve the complete error, timestamp, client version, and target host/port—but never the password.
Fixed diagnostic order
DNS resolution
→ TCP route/firewall/listening port
→ TLS negotiation and certificate identity
→ pg_hba.conf match
→ user authentication
→ database and CONNECT privilege
→ instance/pool connection capacity
→ session initialization settingsResetting passwords or widening privileges before proving the previous layer usually hides the real cause.
Frequent errors
| Error | Meaning | Verify |
|---|---|---|
could not translate host name | DNS/hostname cannot resolve | getent hosts, nslookup, spelling, and private DNS |
connection refused | Nothing accepts the target address/port | Service state, listen_addresses, port, and container mapping |
connection timed out | Network path or firewall drops traffic | Test TCP from the application environment, not a laptop substitute |
no pg_hba.conf entry | No rule matches source/database/user/TLS | Inspect server log and rule order; reload after editing |
password authentication failed | Credential or authentication method mismatch, commonly SQLSTATE 28P01 | Confirm target instance/user and rotate securely |
database ... does not exist | Database absent on this instance, SQLSTATE 3D000 | Connect to postgres and inspect pg_database |
too many connections | Instance/role/database limit exhausted, SQLSTATE 53300 | pg_stat_activity, pool size, and reserved administration access |
certificate verify failed | CA, hostname, validity, or chain mismatch | sslmode, URI host, CA file, and provider rotation notice |
Client verification
psql --version
psql -X "postgresql://app_reader@db.example.com:5432/commerce?sslmode=verify-full"Immediately after success:
\conninfo
SELECT current_database(), current_user,
inet_server_addr(), inet_server_port(),
current_setting('server_version');Minimal server-side checks
SELECT datname, datallowconn, datconnlimit
FROM pg_database
ORDER BY datname;
SELECT usename, application_name, client_addr, state, count(*)
FROM pg_stat_activity
GROUP BY usename, application_name, client_addr, state
ORDER BY count(*) DESC;Use OS access only when needed to inspect listening sockets, firewalls, and PostgreSQL logs. For managed databases, use provider connection diagnostics, network flow logs, and audit logs.
Do not test passwords with trust
Changing pg_hba.conf to trust removes the authentication boundary and does not explain the original failure. Rotate credentials through a controlled channel and identify the matching HBA rule and server log entry.
For a secure successful connection, see psql and SSL. For SQL execution failures, use the SQLSTATE fieldbook.
Last updated on