psql or pgAdmin gets Connection refused from a Postgres container
psql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refusedShort answer
Connection refused means nothing accepted the connection at the address and port you used. Check the container first: is it running, is the port published, and are you using the host port from your machine but the service name and container port from another container? A custom config also needs listen_addresses set to *.
Fix it fast
1Find out which cause you have
See whether the container is up, what it publishes, and whether the server inside answers.
docker compose ps docker compose port db 5432 docker compose exec db pg_isready -U postgres2Match what you see, then jump to its fix
- 1
docker compose port prints nothing, or a different port than the one you connect to.The port is not published, or the host port differsFix - 2
pgAdmin or your app runs in Docker and connects to localhost or 127.0.0.1.Another container uses localhost, or the host port, to reach the databaseFix - 3
pg_isready exits 1 or 2 right after up, and works a few seconds later.The server is still startingFix - 4
The server is up and local checks pass, but other containers get refused.A custom configuration restricts listen_addressesFix
- 1
What does the error look like?
psql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refusedIs the server running on that host and accepting TCP/IP connections?could not connect to server: Connection refused
Cause 1 of 4
The port is not published, or the host port differs
1Check
Only ports under ports: reach the host; expose: does not publish anything. In a mapping the left number is the host port.
docker compose config | grep -A4 ports2Fix
Publish the port and connect to the host port from your machine.
services:
db:
ports:
- "5432:5432"3Verify
The host port answers.
pg_isready -h 127.0.0.1 -p 5432Confirmed by docs.docker.com
Cause 2 of 4
Another container uses localhost, or the host port, to reach the database
1Check
Inside a container, localhost is that container. Containers on one Compose network find each other by service name and use the container port, not the published host port.
docker compose exec pgadmin getent hosts db2Fix
Use the service name as host and the container port in the other service's settings.
host: db
port: 54323Verify
Connect from the other container.
docker compose exec pgadmin sh -c 'getent hosts db'Confirmed by docs.docker.com
Cause 3 of 4
The server is still starting
1Check
The first start runs initialisation, and a depends_on without a health condition does not wait for it.
docker compose exec db pg_isready -U postgres; echo $?2Fix
Add a healthcheck and make the client service wait for it.
services:
db:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
retries: 10
app:
depends_on:
db:
condition: service_healthy3Verify
The client starts only once the database is healthy.
docker compose up -d && docker compose psConfirmed by docs.docker.com
Cause 4 of 4
A custom configuration restricts listen_addresses
1Check
The default is to listen on loopback only. The image's own configuration listens widely; your own file must do it too.
docker compose exec db psql -U postgres -c 'show listen_addresses'2Fix
Set listen_addresses to * in the configuration file you mount.
listen_addresses = '*'3Verify
After a restart the setting shows *.
docker compose restart db && docker compose exec db psql -U postgres -c 'show listen_addresses'Confirmed by postgresql.org
How do I stop it coming back?
- Keep one table of which port each side uses: host port for your laptop, container port between services.
- Give every database a healthcheck and use service_healthy.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Databases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
Node.js in Docker Compose cannot find mysql2/promise
The app works on the host but fails after docker compose up
mysql2/promise is a path inside the mysql2 package.
2 causes, each with a fixDatabases
A container cannot resolve the name of its database container
php_network_getaddresses: getaddrinfo failed
127.0.0.11 is Docker's own DNS server for custom networks.
3 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fixDatabases
Keycloak in a container will not let you create the first admin user
You need local access to create the initial admin user.
Keycloak only lets you create the first admin from a local network connection, and a container does not count.
2 causes, each with a fixDatabases
The MariaDB or MySQL container ignores the root password you set
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
The official MariaDB and MySQL images apply their password variables only while initialising an empty data directory.
3 causes, each with a fix