Connection refused: Is the server running on that host and accepting TCP/IP connections?

What it means

The client sent a connection request to that host and port, and the machine answered “nothing here”. PostgreSQL never saw the attempt: either no server is running, it runs on a different port, or it listens only on other network addresses. User names, passwords and pg_hba.conf don’t come into it yet.

The second line, Is the server running on that host and accepting TCP/IP connections?, is libpq’s hint, not part of the operating system’s answer. When a host name has several addresses, libpq tries each in turn and reports every failure, which is why localhost often fails twice: once on ::1 (IPv6) and once on 127.0.0.1.

Related messages:

• connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory is the same problem on a Unix-domain socket, used when you give no host.
• timeout expired means nothing answered at all, typically a firewall that drops traffic or an address that doesn’t exist.
• could not translate host name "…" to address means the host name doesn’t resolve.

Common causes

1. The server isn’t running. It was stopped, crashed, failed to start after an upgrade or config change, or the Docker container isn’t up.
2. Wrong port. PostgreSQL listens on 5432 by default, but a Docker container is reached on whatever host port it was mapped to, and a second install on the same machine gets another port, such as 5433.
3. The server listens only on localhost. listen_addresses defaults to localhost, so a server installed from packages refuses connections from other machines until you change it.
4. Wrong host. Inside a Docker container, localhost is the container itself, not your Mac or the database container; use the service or container name.
5. A firewall rejects the port on the server or on the way there.

How to fix it

Check that something is listening

From your Mac:

nc -vz <host> 5432

Connection to <host> port 5432 [tcp/*] succeeded! means something is listening, and the problem is elsewhere. Connection refused confirms this error. On the server itself, pg_isready answers the same question in PostgreSQL’s terms:

pg_isready -h localhost -p 5432

To see what’s listening on a port on your Mac:

lsof -nP -iTCP:5432 -sTCP:LISTEN

Start the server

Use whatever manages it: brew services start postgresql@17 for Homebrew, the Start button in Postgres.app, docker start <container> for Docker, sudo systemctl start postgresql on most Linux servers. If it doesn’t stay up, its log says why (docker logs <container> for Docker).

Use the right port

On a connection that works, SHOW port; gives the server’s port. For Docker, docker ps shows the mapping: in 0.0.0.0:54318->5432/tcp, you connect to 54318 on your Mac, and PostgreSQL listens on 5432 inside the container.

Let the server accept network connections

To reach a server from another machine, set listen_addresses in postgresql.conf and restart PostgreSQL (a reload isn’t enough for this setting):

listen_addresses = '*'

'*' means every network interface; a list of specific addresses is tighter. Then add a pg_hba.conf rule for the clients, or the next error will be no pg_hba.conf entry for host. Open port 5432 in the server’s firewall only to the addresses that need it.

For the socket form

With no host, libpq looks for a socket in its default directory (/tmp for Homebrew and most Mac builds). Servers installed from Debian or Ubuntu packages, including the official Docker image, put theirs in /var/run/postgresql. Pass -h localhost to use TCP instead, or -h /var/run/postgresql to name the directory. SHOW unix_socket_directories; tells you where a server puts it.

Reproduce it

With nothing listening on port 55419:

psql -h localhost -p 55419 -U inlet -d inlet -c 'select 1'

psql: error: connection to server at "localhost" (::1), port 55419 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?
connection to server at "localhost" (127.0.0.1), port 55419 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

With no host, psql 18.6 on a Mac looks in /tmp:

psql: error: connection to server on socket "/tmp/.s.PGSQL.55419" failed: No such file or directory
	Is the server running locally and accepting connections on that socket?

To an address that never answers, with connect_timeout=3:

psql: error: connection to server at "10.255.255.1", port 5432 failed: timeout expired

One Docker case looks different. We started PostgreSQL 18.6 in a container with -c listen_addresses=localhost and mapped its port to 55411. The Mac’s port forwarding (OrbStack, here) accepted the connection, then found nothing listening inside, so the client saw:

psql: error: connection to server at "localhost" (::1), port 55411 failed: server closed the connection unexpectedly
	This probably means the server terminated abnormally
	before or while processing the request.

If a container’s port is mapped but you get this message, check listen_addresses inside it.

In Inlet

The connection window shows the server’s message with a hint for common causes. Inlet can also connect through an SSH tunnel, using the system ssh, so ~/.ssh/config and your SSH agent work. Tunnelling to the database’s own machine lets PostgreSQL keep listening on localhost only.