After moving an application or database, “connection refused” may appear even though PostgreSQL starts successfully on the server. The usual causes are a stale hostname, wrong port, service binding only to localhost or a firewall rejecting traffic. Treat a network refusal differently from a PostgreSQL authentication failure: the latter proves that the client reached the server.
Symptoms: what this problem looks like
- Local psql connections work while remote application connections are refused.
- The application still uses the former database endpoint or port after migration.
- One subnet can connect but a new application server cannot.
Why it happens
- listen_addresses or the service binding does not include the target interface.
- Network ACL, host firewall or cloud security group denies the new source.
- DNS, container port mapping or application configuration points to the wrong instance.
Before making changes
Use an authorized administrative account and a maintenance window. Export configuration and capture a rollback point before editing PostgreSQL, container or firewall settings. Never expose the database port to the whole internet to “test quickly”; constrain access to the application hosts.
Start with the least disruptive checks, and stop when the original problem is resolved. The Beginner tab below describes the recommended diagnostic sequence. The Advanced tab helps authorized support teams collect evidence without introducing unrelated changes.
Step-by-Step Troubleshooting
Work through the following steps in order. Check the result after each action and preserve a rollback path for any configuration changes.
Record the precise failing endpoint
From the application’s sanitized configuration, record the hostname, port, database name, source host and full error class without the password. Compare them with the migration runbook and current deployment secrets. A stale port or load-balancer name is cheaper to fix than reconfiguring PostgreSQL.
Resolve the destination from the client
On the application host, resolve the DNS name using the organization’s approved tools. Compare the result with the intended private IP, container service name or managed endpoint. An old DNS record or split-horizon zone can send one environment to the retired server.
Test TCP reachability at the configured port
Use an approved TCP test such as nc -vz hostname 5432 or a platform-specific equivalent from the failing host. A refusal, timeout and authentication error indicate different layers. Note any NAT, proxy, mesh or Kubernetes Service between the client and the database.
Confirm PostgreSQL is running and listening
Inspect service logs and the effective server settings for port and listen_addresses. On the database host use ss -ltn or its equivalent to inspect listening sockets. Do not change listen_addresses to * without also verifying tightly scoped firewall and client access controls.
Validate firewall and security-group scope
Compare allow rules with the actual application egress address, not merely the address on its network interface. Test only the required database port and known source CIDRs. If a rule change is necessary, implement least privilege, document its owner and retest from the affected host.
Distinguish pg_hba.conf and credential errors
Once TCP succeeds, test psql with a low-privilege service account and read the exact server response. “No pg_hba.conf entry” requires a specifically scoped host rule, while “password authentication failed” calls for secret and role verification. Reload configuration using supported tooling and inspect pg_hba_file_rules after edits.
Verify application-specific connection settings
Check SSL mode, connection pool host/port, secret injection and environment-variable precedence. Restart or reload only the affected application process if its configuration is cached, then watch a small set of safe read-only queries before restoring normal traffic.
Correlate the original symptom
Compare the earliest reliable error time with the documented indicators: Local psql connections work while remote application connections are refused. Collect only masked diagnostic data, and do not infer causation solely from recent changes.
Validate the strongest suspected cause
Focus the authorized test on this possible failure: Network ACL, host firewall or cloud security group denies the new source. Use staging or a secondary test account when feasible and document the exact rollback before any production configuration edit.
Confirm fix and watch for regressions
Make a fresh connection from each approved application environment and run a read-only SELECT 1. Confirm TLS policy, correct database identity and stable connection-pool health; monitor rejected connections and request latency for a defined post-migration period. Preserve test evidence and route unresolved issues to the responsible vendor or system owner rather than broadening permissions or disabling protection.
Interpret the results
Use the results of your tests to choose the next action instead of repeating a reset. For this specific issue, compare the following observations with the suspected causes:
- Observation A: Local psql connections work while remote application connections are refused. This supports checking: listen_addresses or the service binding does not include the target interface. Confirm it with a reversible test before making a lasting change.
- Observation B: The application still uses the former database endpoint or port after migration. Compare the affected environment with a known-good case and investigate: Network ACL, host firewall or cloud security group denies the new source.
- Observation C: One subnet can connect but a new application server cannot. If the earlier checks do not change the result, gather stronger evidence around: DNS, container port mapping or application configuration points to the wrong instance.
How to verify the fix
Make a fresh connection from each approved application environment and run a read-only SELECT 1. Confirm TLS policy, correct database identity and stable connection-pool health; monitor rejected connections and request latency for a defined post-migration period.
Common mistakes to avoid
- Opening port 5432 to 0.0.0.0/0 to resolve an address problem.
- Editing pg_hba.conf before proving that PostgreSQL is reachable over TCP.
- Assuming a successful psql command on localhost proves remote clients can connect.
If the problem is still there
Escalate with masked endpoint, source subnet, exact error type, listening socket information and change history. Ask the infrastructure and DBA teams to compare both ends of the same TCP path.
Include the specific step that changed the outcome, what you expected, and what actually happened. This allows the next person to continue from evidence instead of repeating the same unsuccessful tests.
Solution Checklist
Official reference
For up-to-date menus, compatibility rules and product-specific support paths, see PostgreSQL: Client authentication and pg_hba.conf. Product menus and support options can change with software versions and regions.
Editorial note: Follow these instructions only for systems and accounts you are authorized to manage. Verify each result before proceeding. This guide does not claim that one fix applies to every configuration.
Disqus hosts the discussion. Comments load automatically as you approach this section and may use cookies.