scribase
Fix guide

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

  1. 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.

  2. 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)"
  3. 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.

  4. 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

FAQ

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.