Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

psql or pgAdmin gets Connection refused from a Postgres container

Errorpsql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refused

Short 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 *.

  • Applies to postgres Docker image 17 and 18, Docker Compose 2, pgAdmin 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 postgres
  2. 2Match what you see, then jump to its fix

    1. 1docker 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. 2pgAdmin 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. 3pg_isready exits 1 or 2 right after up, and works a few seconds later.The server is still startingFix
    4. 4The server is up and local checks pass, but other containers get refused.A custom configuration restricts listen_addressesFix

What does the error look like?

  • psql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refused
  • Is 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 ports

2Fix

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 5432

Confirmed by docs.docker.com

Did this fix it?

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 db

2Fix

Use the service name as host and the container port in the other service's settings.

host: db
port: 5432

3Verify

Connect from the other container.

docker compose exec pgadmin sh -c 'getent hosts db'

Confirmed by docs.docker.com

Did this fix it?

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_healthy

3Verify

The client starts only once the database is healthy.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.