Prisma says it can't reach the database server, but the database is up
Error: 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
P1001 only inside Docker, while the same URL works from your laptop shellThe URL host is localhost, but the command runs inside a containerFix - 2
The 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
psql also fails, with connection refused or a timeoutNothing is listening on that host and port, or a firewall drops the packetsFix - 4
The 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
- 1
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 ps2Fix
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
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 missing2Fix
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 deploy3Verify
The error now names the host you expect, or the command succeeds.
npx prisma migrate statusConfirmed by prisma.io
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" 54322Fix
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 db3Verify
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
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/ip2Fix
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 statusConfirmed by prisma.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Databases
psql or pgAdmin gets Connection refused from a Postgres container
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the address and port you used.
4 causes, each with a fixServers
Reaching a service on the host's localhost from inside a Docker container
getaddrinfo ENOTFOUND host.docker.internal
Inside a container, localhost is the container itself, not your machine.
5 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
Node.js in Docker Compose cannot find mysql2/promise
The app works on the host but fails after docker compose up
mysql2/promise is a path inside the mysql2 package.
2 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fixDatabases
mongodb-memory-server will not start under Jest or in Docker
NoSystemBinaryFoundError
When mongodb-memory-server fails to start, the real reason is hidden behind a generic message.
4 causes, each with a fix