Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Strapi cannot reach PostgreSQL on 127.0.0.1:5432

ErrorError: connect ECONNREFUSED 127.0.0.1:5432

Short answer

ECONNREFUSED means nothing accepted the connection at that address. Either PostgreSQL is not running or not listening on port 5432, or Strapi is not using the host you think: with no DATABASE_HOST set, its config falls back to 127.0.0.1. Check the server with pg_isready, then check config/database and .env.

  • Applies to Strapi 5, PostgreSQL 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask PostgreSQL directly whether it accepts connections on that address. Exit code 0 is up, 2 means no response.

    pg_isready -h 127.0.0.1 -p 5432; echo "exit code: $?"
  2. 2Match what you see, then jump to its fix

    1. 1pg_isready exits with 2 (no response).PostgreSQL is not running or not listening on that portFix
    2. 2PostgreSQL runs on another machine or in another container, but the error still names 127.0.0.1.Strapi falls back to its default host because the variable is not setFix
    3. 3Strapi runs in a container or another host, and the database is on a host where the server default listen_addresses is localhost.PostgreSQL listens only on localhost but Strapi runs somewhere elseFix

What does the error look like?

  • Error: connect ECONNREFUSED 127.0.0.1:5432

Cause 1 of 3

PostgreSQL is not running or not listening on that port

1Check

Start the service and confirm it is up. The default port is 5432, and the server listens only on localhost unless listen_addresses says otherwise.

sudo systemctl status postgresql
pg_isready -h 127.0.0.1 -p 5432

2Fix

Start PostgreSQL. If it runs on another port, set DATABASE_PORT in .env to match; port changes need a server restart.

sudo systemctl start postgresql
# .env, only if the server uses a different port
DATABASE_PORT=5433

3Verify

pg_isready now exits with 0.

pg_isready -h 127.0.0.1 -p 5432; echo $?

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

Strapi falls back to its default host because the variable is not set

1Check

In the PostgreSQL example of the config, host is env('DATABASE_HOST', '127.0.0.1'), so a missing variable means loopback. Make sure .env sits in the project root and is loaded, and that the production process gets the same variables.

grep -n "DATABASE_" .env
grep -n "host" config/database.js config/database.ts 2>/dev/null

2Fix

Set the real host (and the other connection values) in .env, or give one DATABASE_URL, which overrides the other connection properties.

DATABASE_CLIENT=postgres
DATABASE_HOST=db.example.com
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=change-me

3Verify

Restart Strapi and watch the log for a successful start.

npm run develop

Confirmed by docs.strapi.io

Did this fix it?

Cause 3 of 3

PostgreSQL listens only on localhost but Strapi runs somewhere else

1Check

The default for listen_addresses is localhost, which accepts only local loopback connections. An empty list leaves only Unix sockets.

psql -h 127.0.0.1 -U postgres -c "SHOW listen_addresses;"

2Fix

Set listen_addresses to the interface Strapi will reach (or '*'), restart PostgreSQL (the parameter is read only at start), and allow the client address in client authentication.

# postgresql.conf
listen_addresses = '*'
# then
sudo systemctl restart postgresql

3Verify

From the Strapi host, pg_isready answers 0.

pg_isready -h db.example.com -p 5432

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Commit a .env.example listing every DATABASE_ variable, so none is forgotten on a new machine.
  • Check pg_isready in the deploy script before starting Strapi.
  • Use a connection string (DATABASE_URL) for hosted databases so host, port and credentials travel together.

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.