Corrective Action: Supabase Database Unreachable from WSL2 — 30 Minutes Lost to PostgreSQL Wire Protocol Attempts

← Back to Corrective Actions 2026-03-15

Corrective Action: Supabase Database Unreachable from WSL2 — 30 Minutes Lost to PostgreSQL Wire Protocol Attempts

Date: March 15, 2026 Category: API Behavior Assumption / Infrastructure Limitation Impact: ~30 minutes of session time across 2 context windows wasted on failed connection attempts. Community platform database verification blocked until REST API discovery. Resolution Time: ~30 minutes (from first connection attempt to REST API working)

Incident

What Happened

While setting up the Supabase database for the Value-First Collective community platform (apps/community/), V attempted to connect to the PostgreSQL database from WSL2. The direct database host (db.lrdlfxqdoxzoxgpobbui.supabase.co) resolved exclusively to IPv6 addresses — WSL2 cannot reach IPv6 destinations (ENETUNREACH). Subsequent attempts to use the Supabase connection pooler across 7 AWS regions failed with "Tenant or user not found." The SQL API endpoint (/pg/query) does not exist. Finally, the Supabase REST API (PostgREST) at /rest/v1/ was discovered to work perfectly with the service role key — providing full CRUD access to all tables without requiring PostgreSQL wire protocol connectivity.

Timeline

Time Event
~23:00 First attempt: direct PostgreSQL connection to db.*.supabase.co:5432 — ENETUNREACH (IPv6 only)
~23:05 Added dns.setDefaultResultOrder('ipv4first') — no IPv4 A record exists, same failure
~23:10 Tried Supabase connection pooler (aws-0-{region}.pooler.supabase.com) with username postgres — "Tenant or user not found"
~23:15 Discovered correct pooler username format: postgres.PROJECT_REF — still "Tenant or user not found" (region mismatch likely)
~23:20 Tried 7 AWS regions on both ports 5432 and 6543 — all failed
~23:22 Tried /pg/query SQL API endpoint — does not exist
~23:25 Tried REST API with anon key (sb_publishable_*) — 401 Unauthorized
~23:28 Tried REST API with service role key (sb_secret_*) — SUCCESS. Full Swagger JSON returned.
~23:30 Verified: 9 tables found, 8 spaces seeded correctly, schema complete

Root Cause

Three compounding failures:

  1. WSL2 IPv6 limitation (infrastructure). Supabase direct database hosts (db.*.supabase.co) resolve ONLY to IPv6 AAAA records — no IPv4 A records exist. WSL2 on Windows cannot route IPv6 traffic, returning ENETUNREACH. Node.js dns.setDefaultResultOrder('ipv4first') does not help because there is no IPv4 record to prefer.

  2. Pooler username format and region discovery (API behavior assumption). The Supabase connection pooler requires the username format postgres.PROJECT_REF (not just postgres). Even with the correct format, "Tenant or user not found" was returned — likely because the project's actual AWS region was not among the 7 regions tested. Supabase does not surface the project's region in the dashboard credentials section.

  3. Defaulting to PostgreSQL wire protocol (approach assumption). V's first instinct was to establish a direct PostgreSQL connection — the standard approach for database operations. The Supabase REST API (PostgREST) was not considered until after all wire protocol approaches failed. The REST API provides full CRUD, supports complex queries via URL parameters, and requires only HTTPS — which works perfectly from WSL2.

Category: API Behavior Assumption + Infrastructure Limitation

This represents a pattern where the "obvious" approach (direct database connection) is the wrong approach for the environment. The correct tool was available from the start but not considered because PostgreSQL wire protocol is the default mental model for database access.

Fix Applied

Immediate Resolution

Used the Supabase REST API at https://lrdlfxqdoxzoxgpobbui.supabase.co/rest/v1/ with the service role key for all database verification and operations.

Code/Configuration Changes

File Change
/tmp/check-supabase.cjs Created: table discovery via REST API Swagger paths
/tmp/verify-supabase.cjs Created: data verification (spaces, members, threads, posts)

Verification

$ node /tmp/check-supabase.cjs
Tables found (9):
  members
  mentions
  notifications
  posts
  reactions
  space_follows
  spaces
  thread_follows
  threads

$ node /tmp/verify-supabase.cjs
SPACES (8):
  Welcome (public)
  General Discussion (community)
  Methodology (community)
  Case Studies (practitioner)
  Implementation Support (practitioner)
  Pathfinder Circle (pathfinder)
  AI Agents (community)
  Platform Feedback (community)

MEMBERS (0):
  (none yet - AI members not seeded)

THREADS: 0
POSTS: 0

Schema verification complete.

Prevention Measures

Rules Added

Layer File Rule
Critical Lessons memory/MEMORY.md "NEVER attempt direct PostgreSQL connections to Supabase from WSL2. WSL2 cannot reach IPv6 addresses and Supabase DB hosts are IPv6-only. ALWAYS use the Supabase REST API (/rest/v1/) with the service role key. The REST API provides full CRUD on all tables and requires only HTTPS."
Tech Stack skills/enforcement/vf-tech-stack.md Add Supabase section with REST API access pattern, credentials format, and WSL2 constraint
Self-Correction skills/enforcement/vf-self-correction.md Infrastructure Trigger: "Attempting direct PostgreSQL connection to Supabase" → "Use REST API at /rest/v1/ with service role key"

Detection Triggers

If V catches itself:

  • Writing pg, postgres, psql, or node-postgres connection code targeting Supabase → STOP. Use REST API.
  • Debugging ENETUNREACH, ECONNREFUSED, or DNS resolution errors for *.supabase.co on port 5432/6543 → STOP. The REST API is the correct path.
  • Creating a setup-database script that uses PostgreSQL wire protocol → STOP. Migrations are applied via Supabase Dashboard SQL Editor. Operations use REST API.

Lessons

The "obvious" approach is not always the right approach for the environment. WSL2's IPv6 limitation means any service that resolves to IPv6-only addresses is unreachable via wire protocol. Supabase's REST API is a full-featured alternative that bypasses this entirely. The 30 minutes lost here would have been 30 seconds if the REST API had been the first approach. When working in constrained environments (WSL2, air-gapped systems, restricted networks), check for HTTP/REST alternatives before attempting direct database connections.

Related Incidents

  • 2026-03-08: CRLF token infrastructure — Another WSL2/Windows environment mismatch causing silent failures. Same pattern: the environment has constraints that differ from standard Linux assumptions.
  • 2026-03-11: Sanity write context loss — Post-compaction amnesia leading to trial-and-error instead of consulting documented patterns. Same pattern: not checking the known-working approach first.