Supabase Debugging & Troubleshooting Hub
Every post here starts with a specific error message or broken behavior and ends with a working fix. No abstract theory — just the root cause and the change that resolves it.
RLS & security
9 itemsSupabase RLS Policy Not Working: 2026 Debug Checklist
Supabase RLS policy not working? Find auth.uid nulls, uuid/text mismatches, USING vs WITH CHECK bugs, role leaks, service key traps, and safe fixes today.
Supabase RLS Policy Design Patterns Beyond the Basics
Master advanced Supabase RLS policy patterns for multi-role access, team permissions, and hierarchical authorization.
Next.js + Supabase Production Launch Checklist (47 Items)
47-check pre-launch audit for Next.js 15 + Supabase: security, RLS, performance, observability, auth — every item caused a real incident.
Fix Supabase RLS Infinite Recursion (Production 2026)
"Infinite recursion detected in policy for relation" — your Supabase RLS policy is querying its own table. — practical, code-backed walkthrough.
Test Supabase RLS Policies Before You Ship
The SQL editor and the service key both bypass RLS, so neither proves your policy works. Here is how to test a policy as anon and as two real users.
Supabase 42501: permission denied for schema auth
Querying auth.users from the API or a policy returns 42501. The auth schema is locked on purpose — here is the security definer pattern that works instead.
Supabase 42501 Permission Denied: Schema public & auth
Fix Supabase 42501: missing GRANT USAGE on schema public, or an attempt to write to the protected auth schema. Exact SQL statements for both variants.
Does Supabase service_role Bypass RLS? Yes — Use It Safely
Yes — service_role bypasses every RLS policy. Keep it in SUPABASE_SERVICE_ROLE_KEY, server-side only, never NEXT_PUBLIC_. See the safe Next.js patterns.
Supabase bucket RLS policy for table objects fix
Fix `new row violates row-level security policy for table "objects"` in Supabase Storage by fixing bucket paths and matching `upload` or `upsert` policies.
Auth & sessions
17 itemsSupabase Auth + Middleware: Session Guide for Next.js 15
Supabase auth and session management in Next.js 15: middleware patterns, cookie handling, refresh tokens, MFA, and the silent failures that ruin auth.
Supabase SSR Sessions in Next.js App Router (2026 Guide)
How createServerClient, createBrowserClient and middleware cooperate to refresh the Supabase auth cookie — and why getUser() belongs on the server.
Next.js 15 Middleware: Auth, Rate Limiting & Edge Guide
Next.js 15 middleware patterns: auth, rate limiting, A/B testing, geolocation, bot protection, security headers — full Vercel Edge code.
Supabase Auth Callback Redirect Not Working? Next.js Fix
redirectTo only works when the URL is allowlisted in Supabase Auth settings — otherwise it falls back to Site URL. Next.js callback route included.
Supabase "Error sending confirmation email" (500): 5 fixes
Supabase's built-in SMTP is capped at 2 emails per hour and only reaches team members — configure custom SMTP, then check 4 more causes.
Supabase Auth Session Disappears on Refresh? Fix (2026)
AuthSessionMissingError means your Supabase cookies never reach the server. Fix it with createServerClient plus middleware refresh — full Next.js guide.
Supabase AuthSessionMissingError in Middleware: 5 Fixes
AuthSessionMissingError, AuthRetryableFetchError, 406 responses and redirect loops in Next.js middleware — the root cause and exact fix for each one.
AuthSessionMissingError: Auth session missing! (Next.js fix)
Supabase throws "Auth session missing!" when getUser runs with no session attached. Here is what actually causes it in Next.js and how to fix each case.
Supabase Hangs After onAuthStateChange: The Deadlock
Awaiting a Supabase call inside onAuthStateChange deadlocks the client: the next query anywhere in your app never returns. Here is the cause and the fix.
Better Auth vs Supabase Auth 2026: Honest Verdict
Compare Better Auth and Supabase Auth by identity propagation, RLS, deployment and testing. See what changes when you combine them.
Supabase Auth Error Codes: Fixes + TS Cheat Sheet (2026)
Cause and fix for every Supabase Auth error code — invalid_credentials, weak_password, same_password, over_email_send_rate_limit — with a typed handler.
Supabase vs Firebase in 2026: The Honest Comparison
Supabase vs Firebase in 2026: pricing, database, auth, real-time, storage, and DX compared so you can pick the right backend.
Supabase getClaims() vs getSession(): The Silent Auth Bug
getSession() is unsafe in Next.js Server Components, proxy, and Server Actions. getClaims() is the correct call.
Supabase redirectTo Failing on Vercel Previews: SITE_URL Fix
Auth redirects break on Vercel preview deployments? Add wildcard patterns to Supabase's allowed redirect URLs and set NEXT_PUBLIC_SITE_URL per env.
Fix: Supabase redirectTo Ignored on Magic Link / Email Auth
redirectTo falls back to your Site URL when the exact URL isn't allow-listed. The config and the wildcard pattern for localhost and previews.
Supabase Magic Link: The Production Checklist
Supabase magic links default to a 2-email-an-hour mailer, a localhost Site URL, and single-use links a scanner can burn — the pre-launch checklist.
Fix Supabase: Invalid Refresh Token Already Used
Supabase refresh_token_already_used rejects an obsolete credential. Trace token ancestry, reuse exceptions and local recovery after rotation.
Queries & performance
8 itemsSupabase Connection Pooling: PgBouncer on Vercel Serverless
Configure Supabase PgBouncer pooling for Vercel serverless — avoid connection exhaustion, choose pool modes, tune for production.
Supabase Postgres Functions & Triggers: Developer Guide
Complete guide to Postgres functions and triggers in Supabase. Learn PL/pgSQL, automated workflows, business logic, and database-level validation patterns.
Why Your Supabase Queries Are Slow (And How to Fix)
Supabase queries taking 2-10 seconds? The real causes — missing indexes, N+1 patterns, unoptimized RLS, connection pooling — with copy-paste fixes.
Supabase Realtime Not Receiving Events: Complete Fix
Supabase Realtime subscription connects but receives no events? Fix RLS, postgres_changes filters, stale cleanup, paused projects, and event type mixups.
Cookie "__cf_bm" has been rejected for invalid domain: fix
Firefox logs 'Cookie __cf_bm rejected for invalid domain' on every Supabase asset. Why Cloudflare's cookie is dropped, when it's harmless, when it isn't.
Supabase pgsodium_trg_mask_update: Fix Owner Error
"must be the owner of event trigger pgsodium_trg_mask_update" in Supabase is a Vault/pgsodium ownership bug — the SQL editor workaround and the real fix.
Supabase db push: must be owner of table (SQLSTATE 42501)
supabase db push fails with 42501 when another role owns the table your migration alters. Find the owner, move the table to postgres, then push again.
Fix: Supabase local logs "Backend error" (and old 502s)
Supabase local Studio Logs fail because Logflare mistranslates queries for the Postgres backend. Update to CLI 2.122.0+, or pin Logflare 1.50.15 by hand.
Client & queries
4 itemsSupabase Joins: Nested Selects, !inner, Left Joins (2026)
select('*, other_table(*)') is Supabase's join syntax. Real examples for !inner joins, filtering joined rows and disambiguating two foreign keys.
Insert into multiple tables with one Supabase API call 2026
Insert into several tables with one Supabase request? Wrap the inserts in a PostgreSQL function and call it via the Supabase client.
Fix "supabaseUrl is required" in Supabase JS
createClient() throws supabaseUrl is required when the env var never reached the running app. Fix the prefix, the filename, and restart the dev server.
Fix "More Than One Relationship Was Found" in Supabase
Supabase throws this when two join tables connect the same pair of tables. Disambiguate with alias:table!junction_table in select().
DB ops
3 itemsZero-Downtime Supabase Migrations: Expand/Contract (2026)
Ship Supabase schema changes while traffic flows: expand/contract steps, lock_timeout settings, batched backfills and RLS-safe rollouts wired into CI.
Supabase Connection Pooling: PgBouncer on Vercel Serverless
Configure Supabase PgBouncer pooling for Vercel serverless — avoid connection exhaustion, choose pool modes, tune for production.
Testing Next.js + Supabase: Unit, Integration, RLS, E2E
Four layers that catch real bugs: Jest units, integration on local Supabase, pgTAP for RLS policies, Playwright E2E — plus the CI to run them all.
Coming from Firebase
23 itemsIs It Safe to Expose Firebase API Key to the Public?
Firebase-only API keys can be public. Apply API restrictions, Security Rules and App Check; keep keys for other services separate.
Cloud Firestore vs Realtime Database in 2026
Firestore wins for almost every new app — richer queries, multi-region, saner scaling. Realtime Database survives for one job. The verdict, with numbers.
Firebase Auth IDBDatabase Transaction Error: 2026 Fix
Fix "Failed to execute 'transaction' on 'IDBDatabase'" in Firebase Auth: why firebaseLocalStorageDb closes mid-session and a Next.js persistence fallback.
Fix "Default condition should be last one" (Firebase)
Firebase 9.17.0 broke webpack builds with 'Module not found: Default condition should be last one'. The exports ordering cause, fixed version, and pins.
FirebaseError: Expected first argument to collection() — Fix
Seeing Expected first argument to collection() from Firestore in Next.js? You are missing the db instance from getFirestore(). Fix for the v9 modular SDK.
Firebase webframeworks Not Enabled in GitHub Actions: Fix
Next.js deploy fails in CI with 'experiment webframeworks is not enabled'? Set FIREBASE_CLI_EXPERIMENTS in the workflow. Full YAML, EU region, pitfalls.
Firestore PERMISSION_DENIED: Every Real Cause and Fix
Fix firestore PERMISSION_DENIED: locked-mode rules, undeployed rules, request.auth null, wildcard mismatches and queries broader than your rules allow.
Fix "Assertion failed: resolving hosting target" (Firebase)
A hosting entry with no site or target, or a default-site lookup that failed on an expired login. Name every entry, or run firebase login --reauth.
Fix Firestore 'Host has been set in both settings()' error
Your Firebase module ran twice, so useEmulator() hit a started Firestore. Connect once per instance, or on firebase 11.4.0+ with identical values.
Firebase Hosting 404s Every Route Except index.html
A Next.js static export deploys fine, but every route 404s on Firebase Hosting except the home page. The cause is exact-match serving, and the real fix.
Fix Firestore INTERNAL ASSERTION FAILED (ID: ca9)
Firestore's internal counter can go negative and crash with assertion ca9. One cause is fixed upstream, but the crash still recurs. What to do about it.
Fix npm ERESOLVE: Firebase prerelease peer conflict
A Firebase release candidate can fail a stable-only peer range. Choose compatible stable SDK versions and verify npm install and npm ci.
Fix 'Failed to get document because the client is offline'
With the Firestore emulator, a host passed as https://localhost never connects, so getDoc rejects as offline. Pass the bare host name and the port.
Fix Cannot read properties of undefined (reading 'apps')
Firebase v9 and later have no default export, so import firebase from firebase/app breaks the Next.js build or throws. Use modular or compat imports.
Firebase: Cannot read property 'getProvider' of undefined
getFirestore() was given the config object instead of the FirebaseApp, so it reads app.container and finds nothing. Pass the app from initializeApp().
Firebase Google Sign-in on Vercel: Custom authDomain Fix
On Vercel, a custom authDomain fails because nothing serves /__/auth/handler. Proxy /__/auth/* to firebaseapp.com with a Next.js rewrite.
Fix Firebase 'Invalid site key or not loaded in api.js'
Older SDKs conflict when Auth and App Check both use Enterprise reCAPTCHA. Upgrade the affected SDK and verify the scripts loaded in the browser.
auth/invalid-api-key still throws without a real apiKey
A missing or empty apiKey throws auth/invalid-api-key even with no real project involved. Pass any non-empty string without a colon instead.
auth/popup-closed-by-user fires 8 s late: cause and fix
Firebase Auth waits a fixed 8 s after it sees the popup closed before it rejects. Reset your UI on your own close check and keep the sign-in promise alive.
useEmulator disableWarnings: TS2554 Expected 1 arguments
The namespaced firebase typings declare auth().useEmulator(url) with one parameter. Use connectAuthEmulator, or cast to a local type on compat and v8.
linkWithRedirect fails with the Auth emulator: 3 causes
linkWithRedirect against the Auth emulator fails with argument-error, provider-already-linked or an API key error. Pass the resolver to initializeAuth.
Fix "c(...) is not a function" on Firebase SSR deploy
The minified crash hides a default-export call that fails only in the deployed bundle. The real cause, verified against the GitHub duplicate.
Google sign-in fails on an iOS PWA saved to Home Screen
Google blocks OAuth inside the WKWebView an iOS Home Screen PWA runs in. Why redirect and popup both break, and what still needs checking in 2026.
Other hubs
Next.js + Supabase: The Complete Resource Hub
Everything you need to build production-ready full-stack apps with Next.js 15 and Supabase — authentication, RLS, deployments, performance, and architecture decisions.
Next.js Errors: Build, Dev Server, Rendering & Routing Fixes
Fixes for the Next.js errors developers paste into a search bar: ChunkLoadError, prerender and "use cache" build failures, hydration warnings, the useSearchParams Suspense error, port and next/image configuration.
n8n Automation: Real Workflows from Real Projects
Practical n8n automation guides built from actual client work — CRM lead capture, client reporting, Zapier migration, silent failure debugging, and self-hosted AI with Ollama.
PostgreSQL in Production: Errors, Auth & Query Patterns
PostgreSQL error messages and query patterns you hit running Postgres in production — whether you connect through psql directly or through Supabase, the underlying database is the same.
TypeScript Type Errors: Fixes for Next.js Developers
The TypeScript compiler errors (TS2322, TS2305, TS7016, TS2564 and friends) you actually hit building Next.js apps, with the fix and the type-system reasoning behind it.