dataiotech Labs
dbaguidedbaguideDBAdataxtoolsdataopsphere
dbaguide.com
Home/Error Library/postgresql-connection-refused
Back to Errors
PostgreSQL
PG 14 - 17Connection & Network
4 min read
could not connect to server: Connection refused

PostgreSQL "Connection refused" — Server Down or Network Blocked?

Difference between connection refused, timeout, and no pg_hba entry; triage for listen_addresses, port conflicts, firewalls, and Docker container mappings.

Reviewed by:Senior Database Architect & SRE (dataiotech Labs)
Tested Versions: PostgreSQL 14.10, 15.6, 16.4, 17.0 (Ubuntu 24.04 LTS / Docker 26.1)

Operational Verification & Reliability Metadata

Last Technical Review: 27 Ekim 2026
Tested VersionsPostgreSQL 14.10, 15.6, 16.4, 17.0 (Ubuntu 24.04 LTS, Docker 26.1, Kernel 6.8)
Required PrivilegesSUPERUSER or pg_read_all_stats / pg_signal_backend
Risk Assessment
MediumTerminating active sessions forces application-layer transaction rollbacks
Expected OutputTotal connections drop safely below max_connections threshold in pg_stat_activity
Rollback Procedure:Reset temporary session timeouts, reload PgBouncer or revert pool sizing
PostgreSQL Docs: Connections
First 60 Seconds Emergency Protocol:

The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.

▸Symptom

plaintext
could not connect to server: Connection refused Is the server running on that host and accepting TCP/IP connections?

Target port has no active listener.

▸8-Step Triage Checklist

  1. 1pg_isready -h [host] -p 5432
  2. 2Check process: sudo systemctl status postgresql
  3. 3Check socket binding: sudo ss -ltnp | grep 5432
  4. 4Update binding: ALTER SYSTEM SET listen_addresses = '*'; (Requires service restart).
  5. 5Verify cloud security group / host firewall ingress.
  6. 6Verify Docker container port mapping (-p 5432:5432).
  • •Validated versions: PostgreSQL 14 / 15 / 16 / 17

Other Database Error Triage Playbooks

Other battle-tested diagnostic guides for high-severity database errors.

All Errors (20)
POSTGRESQL5 min

PostgreSQL too many clients already: 6-Step Resolution

Three root causes of FATAL: sorry, too many clients already, single diagnostic query to identify the cause, and permanent mitigation via max_connections and PgBouncer.

POSTGRESQL4 min

PostgreSQL password authentication failed: Root Cause and Fix

Four root causes of psql password authentication failed: incorrect password, md5/SCRAM mismatch, pg_hba.conf rule ordering, and port/cluster confusion. Step-by-step triage.

POSTGRESQL4 min

PostgreSQL duplicate key Error: Sequence Sync Fix

Root cause of duplicate key violations after restore or bulk migration, one-line setval repair, and an automated schema-wide PL/pgSQL DO block.