Skip to content
ohsudo, Home
Databases

PostgreSQL "Connection refused … Is the server running?": find out why nothing answers on 5432

Fix PostgreSQL "connection refused": check that it runs, read why it did not start, then fix listen_addresses, the port, the firewall or Docker.

Beginner3 min readApplies to PostgreSQL 14–18 · Ubuntu · Debian · RHEL / Rocky / AlmaLinux · Docker

by OhSudo ··

Not sure this is your cause?Find it step by step: Can't connect to the database →

Part of a learning path:SQL and PostgreSQL, step by step

The application (or psql) can’t reach the database:

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

Without -h, psql tries the local socket file instead, and the message changes:

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

Connection refused means the network worked, but nothing listens at that address and port. PostgreSQL isn’t running, or it runs but doesn’t listen where the client knocks. (A wrong password would give a different error — see password authentication failed.)

  1. Clientconnects to 127.0.0.1:5432
    TCP
  2. listen_addresses and portwhere PostgreSQL listens
    refused(fails)
  3. Nothing therestopped, or elsewhere(breaks here)
The network worked, and nothing listens where the client knocks: PostgreSQL isn't running, or it listens on another address or port (listen_addresses, port).

TL;DR

Terminal window
pg_isready -h localhost                       # does anything answer?
systemctl status postgresql --no-pager        # is it running?
sudo ss -tlnp | grep 5432                     # where does it listen?

1. Is PostgreSQL running?

Terminal window
pg_isready -h localhost

accepting connections → it runs and listens there (then your client uses another address or port — section 4). no response → continue.

Terminal window
systemctl status postgresql --no-pager

Note

Debian and Ubuntu: postgresql.service is only a wrapper that says “active (exited)” even when the database is down. The real service is per cluster — postgresql@16-main for version 16 — and pg_lsclusters shows every cluster with its port and status (online / down). On RHEL-family systems it’s simply postgresql.

2. Why didn’t it start?

Terminal window
sudo journalctl -u postgresql -n 8 --no-pager
postgres[688]: LOG:  invalid value for parameter "shared_buffers": "1GBB"
postgres[688]: HINT:  Valid units for this parameter are "B", "kB", "MB", "GB", and "TB".
postgres[688]: FATAL:  configuration file "/etc/postgresql/16/main/postgresql.conf" contains errors

On Debian/Ubuntu, read /var/log/postgresql/postgresql-16-main.log too (and journalctl -u postgresql@16-main). The usual reasons:

  • A typo in postgresql.conf — like above: PostgreSQL refuses to start with an invalid setting, and names it.
  • The disk is full — could not write … No space left on device; see No space left on device.
  • Another PostgreSQL already uses the port — could not bind IPv4 address "127.0.0.1": Address already in use; see Address already in use.
  • Permissions on the data directory — data directory "…" has invalid permissions: it must belong to postgres and have mode 0700.

Fix the setting, then start it:

Terminal window
sudo sed -i 's/1GBB/1GB/' /etc/postgresql/16/main/postgresql.conf
sudo systemctl start postgresql
pg_isready -h localhost

3. It runs, but remote clients are refused

By default PostgreSQL listens only on localhost. From the server itself everything works; from another machine (or a container) it’s “connection refused”. Check where it listens:

Terminal window
sudo ss -tlnp | grep 5432
LISTEN 0  200  127.0.0.1:5432  0.0.0.0:*  users:(("postgres",pid=882,fd=6))

To accept connections from the network, three things are needed:

  1. listen_addresses in postgresql.conf — the server’s address, or '*' for all — then restart (a reload isn’t enough for this setting).
  2. A host line in pg_hba.conf for the clients’ network, for example host shop app 10.0.1.0/24 scram-sha-256, then reload.
  3. The firewall must allow port 5432 from those clients (ufw, firewalld, the cloud security group).

Don’t open 5432 to the whole internet; limit it to the networks that need it.

4. The client knocks on the wrong door

  • Another port. On Debian/Ubuntu, a second cluster gets 5433, 5434… — pg_lsclusters shows which port each one has.
  • Docker. Inside a container, localhost is the container itself; a database container is reached by its service name (db:5432), and a database on the host through host.docker.internal — see connection refused to localhost from a container.
  • A database container that isn’t ready yet. It starts listening only after initialization; use a healthcheck with pg_isready and depends_on: condition: service_healthy — the Docker Compose Generator adds both.

Shell, we have a problem!

Similar, but different: timeout expired / Connection timed out — packets are dropped on the way (firewall, wrong IP, routing), so nothing even refuses; see “Connection timed out” vs “Connection refused”. no pg_hba.conf entry for host … — the connection reached PostgreSQL, but no pg_hba.conf line allows it: see that article. FATAL: sorry, too many clients already — it runs fine and is full; check max_connections and connection pools. If the server is up and full, see too many clients already. For everyday admin commands, see the PostgreSQL Admin Cheat Sheet.

$ ./practice.sh

Practice this in the terminal

Open the Terminal Playground with this article’s scenario loaded. It is safe and runs in your browser.

Open the terminal →

Found this useful? Share it.

Tags:#postgresql#connections#systemd#networking#docker#troubleshooting

Found a mistake? Let us know at contact@ohsudo.com.

Tools

Try it yourself

>_

Linux Terminal Playground

A safe Linux shell in your browser, with ready-made scenarios from the articles: services, logs, disks, permissions, firewalls, SSH and more.

{ }

Docker Compose Generator

Pick your services and get a ready-to-run docker-compose.yml with healthchecks, volumes and a .env file.

:443

Port Lookup

What usually runs on port 5432, 6443 or 9090 — and what to check if it’s open.

Articles

Related articles

no pg_hba.conf entry
Databases

PostgreSQL "no pg_hba.conf entry for host": allow this connection, the safe way

Fix PostgreSQL "FATAL: no pg_hba.conf entry for host": read the host, user and SSL in the message, add a narrow rule to pg_hba.conf, reload it, and handle Docker and SSL.

Intermediate · 4 min read

ECONNREFUSED 127.0.0.1:27017
Databases

MongoDB "connect ECONNREFUSED 127.0.0.1:27017": why it refuses, and how to fix it

Fix MongoDB "connect ECONNREFUSED 127.0.0.1:27017" and ::1:27017: start mongod, read exit code 14, check bindIp, IPv6 localhost in Node.js, and Docker service names.

Beginner · 4 min read

ERROR 2002 (HY000)
Databases

MySQL "Can't connect to local MySQL server through socket": find out why (ERROR 2002)

Fix MySQL ERROR 2002 "Can't connect to local MySQL server through socket": is the server running, where is the socket, and why localhost differs from 127.0.0.1.

Beginner · 4 min read