Error: connect ECONNREFUSED 127.0.0.1:5432
Most likely cause: PostgreSQL is not running on that machine
Try first: Check that PostgreSQL is running (pg_isready -h 127.0.0.1 -p 5432)
Likely causes
- PostgreSQL is not running on that machinemost likely
- The app runs in a Docker container and uses localhost or 127.0.0.1, which points at the container itself, not the databasepossible
- PostgreSQL is on a different port or only listens on another address (listen_addresses in postgresql.conf)possible
- The host or port in DATABASE_URL or your connection settings is wrongless likely
How to fix it
Check that PostgreSQL is runningSafe
On the database machine, check whether PostgreSQL accepts connections. pg_isready ships with PostgreSQL; it should say "accepting connections". On Windows, open Services (services.msc) and look for a postgresql-x64 service set to Running instead.
pg_isready -h 127.0.0.1 -p 5432Start PostgreSQL if it's stoppedChanges settings
Linux: run the command shown. macOS with Homebrew: brew services start postgresql (add your version, e.g. postgresql@16). Windows: in Services, right-click the postgresql service and choose Start. Then try your app again.
sudo systemctl start postgresqlSee what is listening on port 5432Safe
If nothing shows, PostgreSQL isn't listening on 5432 (check the port setting in postgresql.conf). On Windows use: netstat -ano | findstr :5432
sudo ss -ltnp | grep 5432In Docker, use the database service name, not localhostSafe
Inside a container, localhost means that container. If your database runs as a service called db in docker-compose.yml, set the host to db (e.g. postgres://user:pass@db:5432/mydb) and make sure the db container is up with docker compose ps.
docker compose psDouble-check the connection settingsSafe
Print or inspect DATABASE_URL (or your host/port settings) and confirm the host and port match where PostgreSQL actually runs. A typo or a leftover value from another machine is easy to miss.
If that didn't fix it
Open the PostgreSQL log (on Linux usually under /var/log/postgresql/) and look for a startup error such as a port already in use or a bad config line, fix it, and start the service again.
When to see a technician
If the database runs on a server or hosting service someone else manages, ask them to confirm it is up and that your machine is allowed to connect.
Quick answers
- What does Error: connect ECONNREFUSED 127.0.0.1:5432 mean?
- Your app tried to connect to a PostgreSQL database on port 5432, but nothing accepted the connection. Usually PostgreSQL isn't running, is listening on a different address or port, or (in Docker) your app is pointing at localhost instead of the database container.
- What causes Error: connect ECONNREFUSED 127.0.0.1:5432?
- PostgreSQL is not running on that machine. (most likely) The app runs in a Docker container and uses localhost or 127.0.0.1, which points at the container itself, not the database. (possible) PostgreSQL is on a different port or only listens on another address (listen_addresses in postgresql.conf). (possible) The host or port in DATABASE_URL or your connection settings is wrong. (less likely)
- How do I fix Error: connect ECONNREFUSED 127.0.0.1:5432?
- Try these in order, safest first: 1. Check that PostgreSQL is running. 2. Start PostgreSQL if it's stopped. 3. See what is listening on port 5432. 4. In Docker, use the database service name, not localhost. 5. Double-check the connection settings.
- What if that didn't fix it?
- Open the PostgreSQL log (on Linux usually under /var/log/postgresql/) and look for a startup error such as a port already in use or a bad config line, fix it, and start the service again.
- When should I see a technician?
- If the database runs on a server or hosting service someone else manages, ask them to confirm it is up and that your machine is allowed to connect.