Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 1: Docker & Node.js Fatal Errors6 min readVerified

How to Fix Prisma Error P1001 in Docker Compose with pg_isready Healthchecks

Resolve Prisma Error P1001: Can't reach database server at localhost:5432 or postgres:5432 in Docker Compose. Fix container bridge DNS, wait for pg_isready healthchecks, and separate prisma generate from prisma migrate deploy.

TL;DR — Immediate Production Fix

Prisma Error P1001 ('Can't reach database server at <host>:5432') inside Docker Compose happens for one of three exact reasons: (1) your DATABASE_URL uses localhost:5432 or 127.0.0.1:5432 instead of the Docker Compose service name (e.g., postgres:5432), causing the app container to knock on its own loopback interface, (2) your Node.js container boots and runs npx prisma migrate deploy milliseconds before the PostgreSQL container finishes initializing its data directory (because standard depends_on only waits for container start, not TCP readiness), or (3) you are calling prisma migrate deploy inside a Dockerfile RUN layer during build time when the runtime Docker network does not exist yet.

Verified Root Causes in Production Environments

  • Loopback Hostname Misconfiguration (localhost vs Service Name): Inside an isolated Docker container, localhost refers to the Node.js container itself, not the host machine or sibling Postgres container.
  • Race Condition on Cold Boot (depends_on Without service_healthy): PostgreSQL takes 2 to 6 seconds to initialize WAL logs and listen on TCP 0.0.0.0:5432 after the container starts.
  • Running Database Migrations at Docker Build Time: Placing RUN npx prisma migrate deploy inside a Dockerfile fails because build containers cannot resolve runtime docker-compose bridge hostnames.

1. Fix Hostname Resolution: localhost:5432 vs Docker Service DNS (postgres:5432)

When developing locally outside Docker, your Node.js app connects to a Dockerized Postgres instance via postgresql://user:pass@localhost:5432/mydb because port 5432 is published to your host machine. However, as soon as you containerize your Node.js or Next.js application inside the same docker-compose.yml file, localhost inside the app container points strictly to the app container's own loopback network namespace.

In Docker Compose, every service registered on a shared user-defined bridge network is automatically discoverable via Docker's embedded DNS server (127.0.0.11) using its exact service key name. If your database service is named postgres, your container DATABASE_URL must use @postgres:5432—and it must always use internal port 5432 even if you mapped host ports like 5433:5432.

.env.docker-vs-local
ini
# ❌ WRONG inside a Docker container (connects to the Node container's own loopback):
# DATABASE_URL="postgresql://vexlo:secret@localhost:5432/appdb?schema=public"

# ❌ WRONG when ports: ["5433:5432"] is used (containers talk on internal port 5432):
# DATABASE_URL="postgresql://vexlo:secret@postgres:5433/appdb?schema=public"

# ✅ CORRECT inside Docker Compose (uses service name 'postgres' and internal port 5432):
DATABASE_URL="postgresql://vexlo:secret@postgres:5432/appdb?schema=public&connect_timeout=15&pool_timeout=15"

2. Eliminate Startup Race Conditions With pg_isready and service_healthy

Even when your hostname is set to postgres:5432, running docker compose up on a fresh volume frequently throws Error: P1001 because Docker starts the postgres container and immediately starts the app container 100 milliseconds later. Meanwhile, the official postgres:16-alpine entrypoint script is still running initdb, creating the database user, and restarting the temporary local socket server before binding to TCP 0.0.0.0:5432.

Fix this race condition permanently by adding a pg_isready healthcheck to the postgres service and configuring depends_on with condition: service_healthy on your application container.

docker-compose.yml
yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: vexlo-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: vexlo
      POSTGRES_PASSWORD: supersecretpassword
      POSTGRES_DB: appdb
    volumes:
      - pg_data:/var/lib/postgresql/data
    networks:
      - backend
    healthcheck:
      # Verify Postgres is accepting TCP connections for the exact user and DB
      test: ["CMD-SHELL", "pg_isready -h localhost -p 5432 -U vexlo -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s

  web-api:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      DATABASE_URL: "postgresql://vexlo:supersecretpassword@postgres:5432/appdb?schema=public&connect_timeout=15"
    networks:
      - backend
    depends_on:
      postgres:
        condition: service_healthy # Waits until pg_isready returns exit code 0!

volumes:
  pg_data:

networks:
  backend:
    driver: bridge

3. Separate Build-Time prisma generate From Runtime prisma migrate deploy

Another frequent cause of Error: P1001 in Coolify, Railway, and Vexlo Cloud deployments is placing npx prisma migrate deploy or static Next.js page pre-rendering (which queries the database) inside a Dockerfile RUN step. During docker build, your container is not attached to your production docker-compose bridge network, so the hostname postgres cannot be resolved.

In your Dockerfile build stage, run ONLY npx prisma generate (which generates the TypeScript client from schema.prisma offline without touching the database). Move npx prisma migrate deploy into your container's runtime CMD or docker-entrypoint.sh script so migrations execute after the container attaches to the live network.

docker-entrypoint.sh
bash
#!/bin/sh
set -e

echo "[Entrypoint] Verifying database connectivity and applying pending Prisma migrations..."
# Run production migrations at container startup, NEVER during 'docker build'
npx prisma migrate deploy

echo "[Entrypoint] Starting Node.js production server..."
exec node server.js

Pre-Deployment Verification Checklist

  • Replace localhost or 127.0.0.1 in DATABASE_URL with the exact Docker Compose service name (e.g., postgres).
  • Always use the internal container port (5432) in DATABASE_URL, regardless of what host port is mapped in ports:.
  • Add a pg_isready healthcheck to Postgres and use depends_on: postgres: condition: service_healthy.
  • Run npx prisma generate at Docker build time and npx prisma migrate deploy at container startup time.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why does Prisma throw P1001 when I run npx prisma migrate dev from my host terminal?

When you run Prisma CLI commands directly on your host machine (outside Docker) while your app runs inside Docker, your host machine cannot resolve the Docker hostname `postgres`. Either run `docker compose exec web-api npx prisma migrate dev` or keep `localhost:5432` in your local `.env` and pass `postgres:5432` inside `docker-compose.yml`'s `environment:` block.

Does npx prisma generate require a live database connection during docker build?

No. `npx prisma generate` only parses your `schema.prisma` file to build the `@prisma/client` TypeScript bindings and Rust query engine binary. You can pass a dummy `DATABASE_URL="postgresql://dummy:dummy@localhost:5432/mydb"` during `docker build` if your framework validates env vars at build time.

Why does Prisma P1001 happen with Supabase or Neon connection poolers?

When connecting to external managed Postgres with PgBouncer on port 6543, you must append `?pgbouncer=true&connect_timeout=15` to `DATABASE_URL` and provide a separate unpooled port 5432 `DIRECT_URL` in `schema.prisma` for migrations.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →