← All posts

Supabase getaddrinfo ENOTFOUND db.<ref>.supabase.co Fix

By Varun Krishnan · Founder, dbdiagramr

Published · Updated · 7 min read

#supabase#postgres#tutorial

Fix Supabase getaddrinfo ENOTFOUND db.<ref>.supabase.co: use the session pooler (5432), or transaction pooler (6543) with prepared statements off.

The short answer

The Supabase direct host uses IPv6 by default. If your app or network is IPv4-only, the hostname has no usable address and Node reports getaddrinfo ENOTFOUND db.<ref>.supabase.co. The fix is the shared pooler: Session mode (port 5432) is the safe default, and Transaction mode (port 6543) works for serverless if prepared statements are turned off.

For the full four-mode table, usernames, SSL settings, and driver fixes, see the Supabase connection string guide.

What the error means

Error: getaddrinfo ENOTFOUND db.xxxxxxxxx.supabase.co

ENOTFOUND means the resolver returned no address your client could use. ENETUNREACH means an IPv6 address was returned but your network has no route to it. ETIMEDOUT means packets were sent but no reply came back, often because a firewall or network path is blocking IPv6.

The pooler error (ENOTFOUND) tenant/user ... not found is a tenant lookup failure, not this DNS failure. See Tenant or user not found for that message.

Why the direct host fails on IPv4

The direct connection string is postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres. That host uses IPv6 by default. IPv4 requires Supabase's paid IPv4 add-on. Supabase's docs describe the add-on as not dual-stack: “enabling it swaps the project's IPv6 (AAAA) DNS record for an IPv4 (A) record, so the project endpoint becomes reachable only over IPv4.”

That is why the same connection string can work on one host and fail on another. An IPv4-only serverless runtime or local network cannot reach the IPv6 endpoint, and a resolver with no A record has nothing to fall back to.

The connection modes

ModeHost and portIP versionUsernamePrepared statementsBest for
Directdb.[ref].supabase.co:5432IPv6 by default; IPv4 add-onpostgresYesMigrations, pg_dump, long-lived IPv6 backends
Dedicated poolerdb.[ref].supabase.co:6543Paid plans; IPv6 by default, IPv4 add-onpostgresNoHigh-performance apps on paid plans
Shared sessionaws-[INDEX]-[REGION].pooler.supabase.com:5432IPv4-only on every planpostgres.[ref]YesPersistent IPv4-only backends, BI tools, database GUIs
Shared transactionaws-[INDEX]-[REGION].pooler.supabase.com:6543IPv4-only on every planpostgres.[ref]NoServerless and edge functions

The dedicated pooler uses the same host as the direct connection, so it hits the same ENOTFOUND on IPv4-only networks unless the project has the IPv4 add-on.

[INDEX] is a pooler cluster index, not part of the region name. A region can have more than one. Copy the host from Dashboard -> Connect instead of composing it.

Fix 1: use the session pooler (recommended default)

Session mode is IPv4-only on every plan, keeps session state, and supports prepared statements. It is the safest default for a persistent backend on an IPv4-only network.

  1. Open Supabase Dashboard -> Connect.
  2. Choose Session pooler.
  3. Copy the whole string and replace only the password placeholder.
  4. Keep the username as postgres.[PROJECT-REF].
psql "postgresql://postgres.[PROJECT-REF]:[PASSWORD]@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgres" -c "select 1"

Fix 2: use the transaction pooler for serverless

Transaction mode is the right fit for serverless and edge functions, which open many short-lived connections. It does not support prepared statements or session-level state such as SET, cursors, LISTEN/NOTIFY, or temporary tables. Turn prepared statements off in your driver.

node-postgres

Omit the name value from the query config. A named query becomes a prepared statement.

import fs from "node:fs";
import pg from "pg";

const ca = fs.readFileSync("./prod-ca-2021.crt", "utf8");

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 1,
  ssl: { rejectUnauthorized: true, ca },
});

// Do not pass a name value here in transaction mode.
await pool.query("select 1");

Download the CA certificate from Supabase Database settings and point the path at your copy. For libpq and psql, sslmode=require encrypts but does not verify the server; use the downloaded CA, or sslmode=verify-full with sslrootcert. See Supabase: connecting with SSL.

node-postgres 8.22: sslmode=require is treated as verify-full, so keep the CA in the ssl object and remove sslmode from the URI. See the full SSL fix.

Supabase's serverless guidance: “Set the pool to 1 connection. The client is shared by every invocation on that warm instance, so this caps the instance, not the request.”

Prisma

Append ?pgbouncer=true to the transaction-pooler URL. This turns off prepared statements in Prisma.

DATABASE_URL="postgresql://postgres.[PROJECT-REF]:[PASSWORD]@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgres?pgbouncer=true"

Use the direct connection or session mode for migrations.

Drizzle with postgres.js

import postgres from "postgres";
import { drizzle } from "drizzle-orm/postgres-js";

const client = postgres(process.env.DATABASE_URL!, { prepare: false });
const db = drizzle({ client });

Python psycopg 3

import psycopg

with psycopg.connect(DATABASE_URL, prepare_threshold=None) as conn:
    with conn.cursor() as cur:
        cur.execute("select 1")

Which mode should you use?

  • Serverless or edge: shared transaction pooler on 6543, prepared statements off.
  • Persistent backend on IPv4-only: shared session pooler on 5432.
  • Persistent backend with IPv6 or the IPv4 add-on: direct connection on 5432.
  • High-performance app on a paid plan: dedicated pooler on 6543, over IPv6 or IPv4 with the add-on.
  • Migrations, pg_dump, backup and restore: direct connection, or session mode if you are IPv4-only.

Related errors

Tenant or user not found
The shared pooler could not match your host and username to a project. Copy the host from Dashboard -> Connect, and make sure the username is postgres.[PROJECT-REF], not postgres.

prepared statement "s0" already exists
You are using transaction mode with prepared statements on. Add ?pgbouncer=true for Prisma, prepare: false for postgres.js/Drizzle, or prepare_threshold=None for psycopg.

ENETUNREACH or ETIMEDOUT
The name resolved, but the IPv6 path is missing or blocked. Use the shared session pooler on 5432.

Full fixes: Tenant or user not found and prepared statement "s0" already exists.

Verify the fix

Check DNS first. On Linux use getent ahosts <host>; on macOS, Windows, or Linux, nslookup <host> is a cross-platform alternative.

getent ahosts aws-[INDEX]-[REGION].pooler.supabase.com
nslookup aws-[INDEX]-[REGION].pooler.supabase.com

Then test the connection and read the catalog:

psql "$DATABASE_URL" -c "select 1"
psql "$DATABASE_URL" -c "select count(*) from pg_catalog.pg_tables where schemaname = 'public'"

Finally, paste the same string into dbdiagramr and confirm the tables render.

Last updated: 2026-10-23. Tested on: 2026-10-23, Supabase shared pooler, session mode (5432) and transaction mode (6543); both introspected a 20-table test schema plus Supabase's auth and storage tables in 2-4 seconds. Paste mode is instant.

Sources

Need to build or decode a URI first? Use the PostgreSQL connection string builder, then open the Supabase ER diagram guide.

Visualize your own database

Paste your PostgreSQL connection string and get an interactive ER diagram in under 10 seconds. No signup required.

Related guides

Try it on your database