Fix Supabase SSR Error: 'AuthApiError: Invalid Refresh Token: Refresh Token Not Found' in Next.js
Fix Supabase `@supabase/ssr` cookie synchronization race conditions in Next.js App Router proxy/middleware and Server Components.
AuthApiError: Invalid Refresh Token: Refresh Token Not Found (or Invalid Refresh Token: Already Used)
# 1. Inspect your Supabase JWT expiration & iat claims locally (offline): npx castov jwt <YOUR_SB_ACCESS_TOKEN> # 2. Ensure @supabase/ssr >= 0.5.2 is installed and updateSession() runs in src/proxy.ts (Next.js 16) or src/middleware.ts.
Root Cause & Mechanism Analysis
Why does this error occur?
Server Components in Next.js cannot write HTTP response cookies directly. When an expired Supabase access token is refreshed inside a Server Component without a `proxy.ts` / `middleware.ts` refreshing and persisting the rotated token first, the single-use refresh token is consumed and discarded.
Frequently Asked Questions
Why should I use `supabase.auth.getUser()` instead of `getSession()` on the server?
Need Zero-Knowledge .env Secret Sync Across Your Engineering Team?
Explore Castov Env Vault for client-side AES-256-GCM encrypted environment sharing, or sponsor this engineering hub.
Related Developer Error Solutions
Browse All 54 GuidesPostgres 42501: new row violates row-level security policy
Resolve PostgreSQL and Supabase Row-Level Security (RLS) INSERT/UPDATE permission errors with proper auth.uid() policies.
Next.js 16: 'middleware' File Convention is Deprecated (Use 'proxy')
Migrate Next.js middleware.ts to the new proxy.ts convention introduced in Next.js 16 App Router.
Next.js Hydration Failed
Resolve Next.js React hydration mismatch errors caused by browser-only APIs (window, localStorage), timestamps, or invalid HTML nesting.
CORS 'Access-Control-Allow-Origin' Missing
Resolve browser cross-origin resource sharing errors by configuring backend HTTP headers and handling preflight OPTIONS requests.