Error: connect ECONNREFUSED talking to Postgres
ECONNREFUSED is a plain TCP-level error: your client tried to open a socket to a host and port, and something actively refused the connection (not a timeout — a refusal, meaning a machine was reachable but nothing was listening, or a firewall rejected it outright). It happens with any raw Postgres driver — pg, postgres.js, knex, Sequelize, a bare psql — not just through an ORM's own wrapped error codes.
Last checked November 18, 2026.
What the error actually means
The full message usually looks like Error: connect ECONNREFUSED 127.0.0.1:5432 (or whatever host and port your connection string points at). ECONNREFUSED is the operating system's TCP-level answer: a packet reached that host and the host (or something in front of it) answered with a hard refusal, as opposed to ETIMEDOUT (no answer at all, usually a firewall silently dropping packets) or ENOTFOUND (the hostname itself did not resolve).
This is a transport-layer failure. It happens before Postgres ever gets to check a username or password, so it is never a credentials problem.
The real causes, most common first
- Nothing is listening on that port: the Postgres server is not running, is still starting up, or was stopped. On a hosted database that pauses or suspends when idle, the same message can appear for a few hundred milliseconds while it wakes.
- Wrong port: 5432 (direct) used where a pooler expects 6543, or vice versa, is one of the most common copy-paste mistakes.
- localhost inside a container: a Docker container's own localhost is itself, not the host machine or a sibling container. Use host.docker.internal (Docker Desktop) or the compose service name on a shared network.
- A firewall, security group or IP allow-list on the database host that does not include the machine or platform your code is running on — common right after a fresh deploy to a new provider.
- The host and port are right but belong to the wrong environment (a local .env still pointing at a teardown-ed preview database, for instance).
How this differs from Prisma's P1001
Prisma wraps the same underlying transport failure in its own error-code system as P1001, with a templated message. ECONNREFUSED is what you see one layer down, from the raw Node.js socket, when the client talking to Postgres is pg, postgres.js, knex, Sequelize, TypeORM or a hand-rolled connection — anything that is not going through Prisma's own error wrapping.
Sources: Prisma: Error message reference
The fix
Step 1
Confirm the server is actually up
Check the host's own dashboard or status page before assuming a network problem, especially on a database that pauses or suspends when idle.
Step 2
Check the host and port in your connection string
Compare against the host's dashboard exactly — a pooler port used where a direct one was needed (or vice versa) is a frequent cause.
sh node -e "const u=new URL(process.env.DATABASE_URL); console.log(u.hostname, u.port)"Step 3
Check Docker networking
If this only fails inside a container, swap localhost for host.docker.internal or your compose network's service name.
Step 4
Check firewall and allow-list rules
Confirm the machine or platform making the request is allowed through, especially right after moving to a new hosting provider.
Connecting to Scribase without ECONNREFUSED
Scribase gives every project a pooled Postgres connection string from the console, reachable over the same TLS endpoint your app already calls for other requests. Direct (unpooled) connections on 5432/6543 are not open from the internet yet; migrations, the console SQL editor and the HTTP serverless driver work today, so a client expecting a raw direct connection needs the pooled URL instead.
Sources: Scribase pricing
Questions people ask
Is ECONNREFUSED the same as a timeout?
No. ECONNREFUSED means something actively refused the connection (reachable, but nothing listening, or explicitly rejected). A timeout (ETIMEDOUT) means no response came back at all, usually a firewall silently dropping the packets instead of rejecting them.
Why does it only happen sometimes?
A database that pauses or suspends when idle can refuse a connection attempt for the moment it takes to wake up, which looks identical to a permanent ECONNREFUSED from the client's side. Retrying after a few seconds tells you which case you are in.
I only see this inside Docker — why?
A connection string with localhost or 127.0.0.1 inside a container refers to the container itself. Use host.docker.internal on Docker Desktop, or the service name from your compose file on a shared Docker network.
How is this different from Prisma's P1001?
They are the same underlying transport failure. Prisma wraps it as P1001 with its own templated message; ECONNREFUSED is what shows up from a raw driver (pg, postgres.js, knex, Sequelize) that does not go through Prisma's error-code system.