PostgreSQL: could not connect to server, connection refused

ERRORSQLSTATE 08006connection_failure

could not connect to server: Connection refused

Postgres refused the TCP connection, or nothing was listening. The server may be down, listening on another port or address, or blocked by a firewall. Confirm it is running and reachable on the host and port you used.

What this error means

This is a client-side error from libpq: it tried to open a TCP connection and the operating system refused it. The query never reached a running Postgres.

Common causes are that the server is not running, it listens only on localhost, the port is wrong, or a firewall or security group blocks it.

How to fix it

The server is not running or not reachable

Check it is up and accepting connections on that host and port.

bash

pg_isready -h localhost -p 5432

Postgres only listens on localhost

Allow remote TCP, then restart Postgres.

text

# postgresql.conf
listen_addresses = '*'
# then restart Postgres

A firewall blocks the port

Open port 5432 (or your port) in the firewall or cloud security group.

Wrong host in a container

Inside Docker, localhost is the container itself. Connect to the Postgres service name or host IP, not localhost.

How to avoid it next time

Confirm listen_addresses and firewall rules whenever you expose Postgres beyond localhost.
Use the correct service host in containerized setups.

Varies by version

This is a client-side libpq message, so it has no server SQLSTATE. 08006 (connection_failure) is the nearest error class. Newer libpq prints a longer form naming the host, IP, and port.

Frequently asked questions

The server is running, why is it refused?

It may be listening only on localhost, on a different port, or blocked by a firewall. pg_isready against the exact host and port tells you which.

I get this from a Docker container.

Inside Docker, localhost is the container itself. Connect to the Postgres service name or host IP instead of localhost.

Stop struggling with SQL

Use FluentDB, the AI database client for macOS.

Download for Mac PostgreSQL client for Mac

Part of the PostgreSQL error reference. Last reviewed 2026-07-31.