Postgres connection refused on localhost:5432 — fix it now

Yeah, that error's a classic. You're staring at a wall of red text and just want it gone. Let's cut to the chase.

The fix that works 90% of the time

Stop what you're doing and check if Postgres is actually running. On most Linux systems, it's a service. On macOS, it might be Homebrew or Postgres.app. On Windows, it's a Windows service.

First, try to connect locally using the Unix socket. That bypasses TCP entirely and tells you if the server itself is alive:

psql -U postgres -h /var/run/postgresql

If that works, the server is up but not listening on TCP. If it fails with "No such file or directory" or "Connection refused", the server isn't running. Period.

Now, start it. On Ubuntu or Debian:

sudo systemctl start postgresql

On RHEL/CentOS/Fedora:

sudo systemctl start postgresql-14   # or your version

On macOS with Homebrew:

brew services start postgresql@14

On Windows, open Services (Win+R, type services.msc), find postgresql-x64-14 (or whatever version), and hit Start.

After it's running, check the status:

sudo systemctl status postgresql

You want to see active (running). Then try your connection again. That's it. That's the fix for the majority of cases.

Why this works

Postgres isn't like a web server that auto-starts with every request. It's a database daemon that needs to be running before any client connects. When you install Postgres, the service is usually set to start on boot, but sometimes it doesn't, especially after a reboot or a package update.

The error message is misleading though. It says "Is the server running on host \"localhost\"" — and that's the first thing you check. But there's a second part: "accepting TCP/IP connections". Even if the server is running, it might not be accepting TCP connections on port 5432. That's usually a configuration issue, not a service issue.

Less common variations and their fixes

1. Postgres is running but bound to the wrong address

Check the listen_addresses setting in postgresql.conf. By default, it's localhost, which is fine for local connections. But if someone changed it to a specific IP, or set it to * (all interfaces), you might still get refused if there's a firewall issue.

Find your config file:

sudo find / -name postgresql.conf 2>/dev/null

Look for this line:

listen_addresses = 'localhost'   # or '*' or an IP

If it's set to something odd, change it to 'localhost' or '*' if you need remote access, then restart Postgres.

2. Port 5432 is already in use

If you've got another instance of Postgres running (or some other service squatting on 5432), the new one will refuse connections. Check with:

sudo netstat -tulpn | grep 5432

You might see two entries. If the second one is listening on a different interface, that's your problem. Stop the extra instance or change the port.

3. pg_hba.conf is blocking your connection

This is the sneaky one. The server runs fine, but it rejects your TCP connection because of host-based authentication rules. The error might be different (like "no pg_hba.conf entry"), but sometimes you get a generic connection refused if the server is configured to only accept Unix socket connections.

Open pg_hba.conf (same directory as postgresql.conf) and look for lines like:

host    all             all             127.0.0.1/32            scram-sha-256

If you don't have a host line for 127.0.0.1, TCP connections from localhost are rejected. Add one, or change the method to trust for testing (don't leave it like that in production). Then reload:

sudo systemctl reload postgresql

4. IPv6 vs IPv4 mismatch

If your client uses localhost, it might resolve to ::1 (IPv6) first. If Postgres is only listening on IPv4 (127.0.0.1), you get a connection refused. Try connecting to 127.0.0.1 instead of localhost:

psql -h 127.0.0.1 -p 5432 -U postgres

If that works, you've got an IPv6 issue. Either set listen_addresses = '*' to cover both, or change your client to use 127.0.0.1.

Prevention: stop this from happening again

Here's what I do after any Postgres install or restart:

1. Enable the service to start on boot. On systemd systems: sudo systemctl enable postgresql. That way, reboots don't leave you stranded.
2. Check your logs after a failed connection. Postgres logs are usually in /var/log/postgresql/ or /usr/local/var/log/postgresql/ on macOS. The log will tell you exactly why it refused the connection — don't guess when the answer's right there.
3. Keep your config files under version control. If you're messing with postgresql.conf or pg_hba.conf, back them up before editing. I've seen more than one production outage from a typo in those files.
4. Use a connection wrapper or script. If you're constantly connecting from different apps, standardize the hostname and port. Use 127.0.0.1 instead of localhost to avoid IPv6 weirdness.

One last thing — don't bother with restarting Postgres every time you change the config. Use reload. It picks up changes to pg_hba.conf without dropping connections. You only need a full restart for listen_addresses and other main settings.

That's it. Go fix your connection and get back to work.