PostgreSQL connection refused: pg_hba, listen_addresses, and TCP diagnosis

An application cannot reach PostgreSQL. The client reports either “Connection refused,” a hang until timeout, or “no pg_hba.conf entry.” These three symptoms point to different layers. Mixing them up leads to wasted restarts, overly broad firewall rules, or pg_hba.conf edits that never take effect. Work through the transport layer first, then the network path, then the authorization layer.

PostgreSQL defaults to binding only to the loopback interface. A fresh installation or container image rejects remote TCP attempts before pg_hba.conf is consulted. Changing listen_addresses requires a restart; changing pg_hba.conf only requires a reload. The diagnostic sequence is: confirm the listener, confirm the path, then confirm the rule.

What this means

A PostgreSQL connection spans three layers. The transport layer: the postmaster binds to an address and port. The default listen_addresses is localhost, so remote TCP attempts fail with ECONNREFUSED unless this is changed. The network path: firewalls, cloud security groups, and routing must allow the SYN packet to reach the port. If they do not, the client sees a timeout. The authorization layer: once the TCP handshake succeeds, pg_hba.conf decides whether the source IP, database, and user are allowed. A mismatch produces a PostgreSQL-level error such as “no pg_hba.conf entry for host,” not an OS-level connection refused.

The Docker official image also defaults to localhost, so publishing the container port does not help unless you override the setting inside the container. On IPv4-only hosts, setting listen_addresses to :: can log “could not bind IPv6 address: Address not available.” PostgreSQL skips IPv6 listening in that case, so IPv6 clients cannot connect even if :: is listed.

Because these layers fail with different symptoms, the fix for one will not help the other. Restarting PostgreSQL because of a firewall timeout wastes minutes. Adding a pg_hba.conf rule when listen_addresses is still localhost will never work.

flowchart TD
    A[Client connection attempt] --> B{What does the client report?}
    B -->|Connection refused| C[Check listen_addresses
and port binding]
    B -->|Timeout| D[Check firewall and
network path]
    B -->|No pg_hba entry| E[Check pg_hba.conf
rule order and match]
    C --> F[Verify with ss -tlnp
and SHOW port]
    D --> G[Check OS firewall
and cloud security groups]
    E --> H[Query pg_hba_file_rules
and SHOW hba_file]

Common causes

Quick checks

Run these read-only checks before changing any configuration.

# Verify the bound address and port from inside PostgreSQL
psql -c "SHOW listen_addresses;" -c "SHOW port;"

# Show the active pg_hba.conf path and all parsed rules
psql -c "SHOW hba_file;" -c "SELECT line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules WHERE error IS NULL;"

# Check for syntax errors in pg_hba.conf that prevent rule loading
psql -c "SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;"

# Inspect listening sockets at the OS level
ss -tlnp | grep -E ':5432\b'

# Test TCP reachability from the client without using the PostgreSQL protocol
nc -vz <hostname> 5432

# Identify the actual server IP and port this session reached
psql -c "SELECT inet_server_addr(), inet_server_port();"

How to diagnose it

Follow this sequence to avoid hopping between layers.

1. Classify the client error. An immediate “Connection refused” means the OS received the SYN and returned RST because nothing is listening on that IP:port. A hang followed by timeout means the SYN never reached a listener, usually because a firewall or security group dropped it. A “no pg_hba.conf entry” or “password authentication failed” means TCP succeeded and PostgreSQL is actively rejecting the connection at the auth layer.

2. Confirm the listener. Run SHOW listen_addresses;. If the value is localhost, the server rejects remote TCP attempts. This parameter accepts a comma-separated list of hostnames or IP addresses. The special value * binds all interfaces. An empty string disables TCP entirely. Changing this parameter requires a full server restart; reloading is not sufficient.

3. Confirm the port. Run SHOW port;. Multiple PostgreSQL minor versions installed on the same host sometimes use different default ports. If the client points to 5432 but the instance listens on 5433, the client gets a connection refused even though the server is healthy.

4. Check OS-level binding. Use ss -tlnp or netstat -tlnp to verify that a process listens on the expected interface and port. If PostgreSQL logs contain “could not bind IPv6 address: Address not available,” the host lacks IPv6 support and the server skipped IPv6 listening. This explains why IPv6 clients cannot connect even if listen_addresses includes ::.

5. Test the network path. From the client, run nc -vz <server> <port>. Refusal means the packet reached the OS but nothing is bound there. Timeout means check host-level firewalls (ufw, firewalld) and cloud security groups. An open OS-level rule is not enough if the cloud layer blocks it.

6. Inspect pg_hba.conf. Run SHOW hba_file; to confirm you are editing the file the server reads. Query pg_hba_file_rules to see the parsed view (available since PostgreSQL 10). Rows with a non-null error column indicate malformed lines that PostgreSQL skipped. Check order carefully: records are evaluated top-down, and the first match wins. A broad reject rule above a narrow allow rule silently blocks traffic.

7. Apply the correct activation method. If you changed pg_hba.conf, activate it with SELECT pg_reload_conf(); or pg_ctl reload. Existing connections are not dropped. If you changed listen_addresses, schedule a restart. In a container, verify that the startup logic overrides listen_addresses; the official postgres image defaults to localhost, and publishing the port with -p does not change the bind address inside the container.

Metrics and signals to monitor

Fixes

listen_addresses excludes the client

Change listen_addresses to the interface IP, or * to accept from all interfaces. Prefer explicit interface addresses in security-sensitive environments because * exposes PostgreSQL on every attached network. After changing this parameter, restart PostgreSQL.

Tradeoff: Restarting drops existing connections. Plan for a maintenance window or apply the change to a replica during failover.

Firewall or security group blocks the port

Open TCP to the client subnet at the OS firewall layer and at any cloud network layer. Restrict the source CIDR to the smallest necessary range. Avoid opening 5432 to 0.0.0.0/0.

Tradeoff: Tighter CIDR ranges require maintenance when client IPs change, but broad rules increase attack surface.

pg_hba.conf has no matching entry

Add a record that matches the client source IP, target database, and user. The standard record format includes TYPE, DATABASE, USER, ADDRESS, and METHOD fields. Use hostssl if TLS is required, or host for either SSL or non-SSL depending on your threat model. Prefer scram-sha-256 for password authentication. MD5 is deprecated; migrate away from it if still in use.

Tradeoff: Adding host all all 0.0.0.0/0 scram-sha-256 is convenient but removes network-level compartmentalization. Prefer multiple specific rules over one broad rule.

pg_hba.conf record order blocks valid traffic

Move specific allow rules above generic reject rules. pg_hba.conf is read top-down and the first match terminates evaluation. A common mistake is placing a default reject line above application-specific allow rules.

Tradeoff: None. Correct ordering is strictly safer and more correct.

Container image binds to localhost

Override listen_addresses inside the container to * via a custom postgresql.conf or an environment variable that your entrypoint respects. Publishing the container port with -p 5432:5432 only maps the host port; it does not change what address the server binds to inside the container.

Tradeoff: Binding to * inside a container is usually acceptable because the container network namespace is already isolated, but verify that the orchestrator or host firewall enforces the desired network boundaries.

Prevention

• Explicit binding. Set listen_addresses to explicit interface IPs rather than * whenever possible. Document why each IP is listed.
• Version control for pg_hba.conf. Track pg_hba.conf in Git or configuration management. After every reload, run SELECT * FROM pg_hba_file_rules WHERE error IS NOT NULL;.
• Staging reload tests. Test pg_hba.conf reloads in staging. Syntax errors do not prevent reload, but PostgreSQL skips malformed lines.
• Client-side validation. After network or auth changes, run nc -vz from an application host, then connect with psql. Test reachability and authorization separately.
• Bind failure monitoring. Monitor PostgreSQL logs for “could not bind” messages. These indicate port conflicts or IPv6 dual-stack issues.

How Netdata helps

• Correlate pg_stat_activity counts with system TCP metrics to distinguish a saturated listener from an absent one.
• Detect PostgreSQL log anomalies, including bind failures and pg_hba.conf reload events.
• Track connection state breakdowns (active, idle, etc.) to spot drops after configuration changes.
• Alert on rapid connection metric changes that accompany listener or auth misconfiguration.

Related guides

• How PostgreSQL actually works in production: a mental model for operators
• PostgreSQL connection exhaustion: detection, diagnosis, and prevention
• PostgreSQL monitoring checklist: the signals every production database needs
• PostgreSQL monitoring maturity model: from reactive to self-healing
• PostgreSQL FATAL: too many connections - causes and fixes