Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Prisma says it can't reach the database server, but the database is up

ErrorError: P1001: Can't reach database server at `localhost`:`5432`

Short answer

P1001 is Prisma's catch-all for any failed connection, even a wrong password, so do not trust the label. Run a plain psql test with the same URL from the same place the command runs. If psql fails too, the cause is the host name, the port, a sleeping database, or the network, never Prisma itself.

  • Applies to Prisma ORM 6 and 7, PostgreSQL 16, Docker Compose v2, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Take the URL Prisma uses, drop Prisma-only parameters such as schema or connection_limit, and test it with psql from the same machine or container that runs the Prisma command. The real error shows up here.

    test -n "$DATABASE_URL" && echo set || echo missing
    psql "$DATABASE_URL" -c 'select 1'
  2. 2Match what you see, then jump to its fix

    1. 1P1001 only inside Docker, while the same URL works from your laptop shellThe URL host is localhost, but the command runs inside a containerFix
    2. 2The host in the error is not the one you typed, or the test above prints missingThe variable is missing or Prisma reads a different URL than you thinkFix
    3. 3psql also fails, with connection refused or a timeoutNothing is listening on that host and port, or a firewall drops the packetsFix
    4. 4The first command after a quiet period fails and the next one works, or the host resolves only to IPv6 and the client has no IPv6 routeA serverless database was asleep, or the host only has an IPv6 addressFix

What does the error look like?

  • Error: P1001: Can't reach database server at `localhost`:`5432`
  • Please make sure your database server is running at `localhost`:`5432`.

Cause 1 of 4

The URL host is localhost, but the command runs inside a container

1Check

Inside a container, localhost is that container itself, not the machine that runs the database. Look at the host part of the URL and at the service name in your compose file.

grep -n "DATABASE_URL" .env docker-compose.yml compose.yaml 2>/dev/null
docker compose ps

2Fix

Use the Compose service name as the host and the container port, not the published host port. Keep localhost with the published port only for commands you run on the host.

# compose.yaml: the database service is called "db", published as 5433:5432
# URL for code running inside the Compose network
DATABASE_URL="postgresql://app:secret@db:5432/app"
# URL for prisma commands run on your own machine
DATABASE_URL="postgresql://app:secret@localhost:5433/app"

3Verify

Run the same psql test from the place where Prisma runs.

docker compose run --rm app sh -c 'psql "$DATABASE_URL" -c "select 1"'

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

The variable is missing or Prisma reads a different URL than you think

1Check

CI jobs, build phases and prisma.config.ts often use a different variable than the app. Prisma ORM 7 reads the migration URL from datasource.url in prisma.config.ts, which may name DIRECT_URL.

grep -n "url" prisma.config.ts
test -n "$DIRECT_URL" && echo set || echo missing

2Fix

Set the variable that the config names, in the exact step that runs the migration. Percent-encode the characters @ : / and # when they appear in a password.

export DIRECT_URL="postgresql://app:p%40ss@db.example.com:5432/app?sslmode=require"
npx prisma migrate deploy

3Verify

The error now names the host you expect, or the command succeeds.

npx prisma migrate status

Confirmed by prisma.io

Did this fix it?

Cause 3 of 4

Nothing is listening on that host and port, or a firewall drops the packets

1Check

Test the TCP port on its own. If it fails, check the name, the route and the firewall rules or allow list on the database side. A corporate VPN can also block port 5432.

DB_HOST=db.example.com
nc -vz -w 5 "$DB_HOST" 5432

2Fix

Start the database or correct the host and port. On a cloud database, add the client's address to the firewall, security group or allow list. For CI runners with changing addresses, run the migration from inside the database's network.

# example for a local container
docker compose up -d db
docker compose logs --tail 20 db

3Verify

nc succeeds, then psql returns one row.

nc -vz -w 5 db.example.com 5432
psql "$DATABASE_URL" -c 'select 1'

Confirmed by prisma.io

Did this fix it?

Cause 4 of 4

A serverless database was asleep, or the host only has an IPv6 address

1Check

Scale-to-zero databases such as Neon suspend after 5 minutes idle. Separately, check whether the host name has IPv4 records at all.

getent --no-addrconfig ahosts db.example.com
curl -6 https://ifconfig.co/ip

2Fix

For a waking database, add connect_timeout=15 to the URL so Prisma waits for it. For an IPv6-only host, use a provider address or pooler that has IPv4, or run the command from a network with IPv6.

DATABASE_URL="postgresql://USER:PASSWORD@HOST/DB?sslmode=require&connect_timeout=15"

3Verify

Run the command after the database has been idle and it connects on the first try.

npx prisma migrate status

Confirmed by prisma.io

Did this fix it?

How do I stop it coming back?

  • Keep a separate DIRECT_URL secret for migrations in every environment that migrates, and print only whether it is set, never its value.
  • Start every migration step with a psql or nc test so the real error appears before Prisma's generic one.
  • Use the Compose service name between containers and keep localhost for commands you run on the host.
  • Add a health check to database containers so dependent steps wait until it accepts connections.

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.