IPv4 and IPv6

The “could not translate host name” error

Your database's hostname is crucial for establishing a direct connection. It resolves to the underlying IP address of your database.

Today we are solving the one and only “could not translate host name” error — the symptom when your stack and Supabase’s network don’t match.

Deploy works locallypsql / app OK

Same code on serverconnection hangs

Often the missing piece is IPv6 vs IPv4.

Section 1 — The problem

Every device has an address — two versions

IPv4 looks like four groups of numbers (older standard). IPv6 is longer — more space, same job: identify a host on the network.

IPv4

192.168.1.1

Dotted decimal · familiar tooling

IPv6

2607:f8b0:4006:819::200e

Hex groups · the replacement

Why it matters

IPv4 space is tiny — and mostly assigned

There are about 4.3 billion possible IPv4 addresses. IPv6 was designed for a vastly larger space. (Bar lengths are conceptual, not to scale.)

Relative address space (illustrative)

IPv4 theoretical space~4.3×10⁹

IPv6 theoretical space~3.4×10³⁸

We’ve largely run out of free IPv4 — carriers and clouds still ship a lot of IPv4-only paths.

Incompatibility

It’s like having a phone that only dials 7-digit numbers trying to call an 11-digit number — and the format simply doesn’t match.

7-digit dialer

Can’t complete the call

11-digit number

Supabase

Direct DB host → IPv6 by default

Supabase’s direct database hostname resolves to an IPv6 address by default. If your server or network is IPv4-only, the connection attempt fails.

Section 2 — Diagnose

Two commands

Check 1: Does this machine speak IPv6? Check 2: What does DNS say for the database host — AAAA vs A?

curl -6 https://ifconfig.co/ip — see if you get an IPv6 route.
nslookup -type=AAAA db.[ref].supabase.co — IPv6 record.
nslookup -type=A db.[ref].supabase.co — IPv4 record (may be empty without add-on).

You can also use test-ipv6.com in a browser.

Animated example

Run the checks (demo output)

Click a scenario to animate sample CLI output — useful for B-roll or live demo.

demo@server ~ %

Section 3 — Fixes

Four ways forward on IPv4-only

If your system doesn’t support IPv6, pick one of these (often pooler or SDK first).

1 · Supavisor stringsTransaction or session pooler — IPv4-friendly host

2 · Supabase client SDKHTTPS to Data API — not a raw DB socket

3 · IPv4 add-onPaid plan · dedicated IPv4 · DNS swaps to A

4 · Enable IPv6On your cloud VPC / network if available

Fixes 1 & 2

Pooler vs SDK path

Supavisor connection strings use an IPv4-compatible pooler. supabase-js (and friends) talk to the project URL over HTTPS — not a direct Postgres wire connection.

Pooler (example)

🖥

Your app

postgres.[ref] @ regional pooler

∞

Supavisor

Transaction or session mode

🐘

Postgres

Backend connections pooled

Client SDK

⚡

supabase-js

anon / service or publishable / secret keys

🔒

https://[ref].supabase.co

Data API (PostgREST) + platform

🗄

DB · Auth · Storage · Realtime · Edge

Works on IPv4 and IPv6

Fix 3

IPv4 add-on — what DNS actually shows

Enable Dedicated IPv4 under Project Settings → Add-ons (paid plan, about $4/mo). For db.[ref].supabase.co, DNS is updated so the hostname targets your dedicated IPv4. In practice, AAAA may return no answer after that — that is expected, not a broken IPv6 stack.

Example ref cqesudmnzjvyhffjvipn — your output may vary slightly by resolver.

Fix 4

Turn on IPv6 where you deploy

Many cloud providers support IPv6 but leave it off by default. If your VPC, subnet, or load balancer can get a public IPv6 address, enabling it gives your workloads a native path to IPv6-only endpoints — including the direct DB host.

When this helps

You need raw Postgres (migrations, ORM direct)+

You control the network stack+

You prefer not to use pooler / add-on~

Check your provider’s docs for “IPv6” or dual-stack VPC — naming varies.

Section 4 — Summary

Direct host is IPv6-first — you have options

If you’re on IPv4-only: use the pooler, use SDKs, pay for the IPv4 add-on, or enable IPv6 where you deploy.

PoolerFastest fix for many servers

SDKApp code via HTTPS API

IPv4 add-onNeed raw direct IPv4

IPv6 on infraEnd-to-end v6 path

That’s the IPv4 and IPv6 story: two commands to diagnose, several ways to fix it.