Bug Description
When using createServerClient from @supabase/ssr within Next.js App Router API Routes (Route Handlers) or Server Components, the call to supabase.auth.getUser() consistently fails with AuthSessionMissingError: Auth session missing!. This occurs even though a valid sb-<project_ref>-auth-token cookie is present in the incoming HTTP request headers and the Supabase middleware (using createMiddlewareClient) appears to be functioning correctly for session refresh and route protection.
Initial investigation suggested potential incompatibility with newer Next.js (v14.2+, v15+) stricter handling of the cookies() API from next/headers, sometimes manifesting as Error: cookies() should be awaited when using synchronous callbacks within the @supabase/ssr client configuration. However, even after attempting workarounds like await cookies() or using potentially compatible versions of @supabase/ssr (up to 0.6.1), the underlying AuthSessionMissingError persists when getUser() is called from the API Route context. Workarounds involving manually extracting the token from the cookie and using it in the Authorization header with @supabase/supabase-js also failed, indicating the cookie value format set by @supabase/ssr is not a standard JWT or easily parsable JSON.
To Reproduce
Steps to reproduce the behavior:
Clone the minimal reproduction repository: https://github.com/zibbie/minimal-supabase-ssr-nextjs-issue
Create a .env.local file in the project root based on .env.local.example using your Supabase project credentials.
Run npm install.
Run npm run dev. Note the port used (e.g., ).
Open http://localhost:/login in your browser and log in with a valid Supabase user. You should be redirected to /dashboard.
Open browser developer tools, navigate to Application/Storage -> Cookies -> http://localhost:. Find the sb-<YOUR_PROJECT_REF>-auth-token cookie and copy its value. Ensure it's cleaned (no base64- prefix or surrounding quotes).
Open a terminal and execute the following curl command (replace and <PASTE_CLEANED_COOKIE_VALUE_HERE>):
curl -X GET
-H "Cookie: sb-<YOUR_PROJECT_REF>-auth-token=<PASTE_CLEANED_COOKIE_VALUE_HERE>"
-v
http://localhost:/api/test-auth
Use code with caution.
Bash
Observe the curl response (returns 401 Unauthorized) and the server logs (npm run dev terminal shows the AuthSessionMissingError originating from the /api/test-auth route).
Expected Behavior
The curl request to /api/test-auth should return an HTTP 200 OK status with the authenticated user's data (e.g., { "userId": "...", "email": "..." }). The server logs should indicate successful authentication within the API Route.
Actual Behavior
The curl request returns HTTP 401 Unauthorized with the body {"error":"Not authenticated","details":"Auth session missing!"}.
The server logs show the following error originating from the supabase.auth.getUser() call within the app/api/test-auth/route.ts file:
[API Prefs SSR] Error: Not authenticated AuthSessionMissingError: Auth session missing!
[API Prefs SSR] Auth Error details: AuthSessionMissingError: Auth session missing!
at ... (stack trace pointing to GoTrueClient.js) ...
(Optional: Mention the cookies() should be awaited error if it appeared reliably with specific Next.js/SSR versions during testing, e.g., Next.js 15 + SSR 0.5.x)
System information
OS: macOS Sequoia 15.4
Browser (for login): [np. Chrome, Firefox, Safari]
Version of Node.js: v22.13.1
Version of @supabase/ssr: 0.6.1 (also tested with 0.5.2, 0.4.1 - issue persists)
Version of @supabase/supabase-js: ^2.49.3
Version of next: 14.2.28 (original app), 15.2.4 (minimal reproduction)
Additional context
The issue occurs specifically when calling supabase.auth.getUser() from an API Route (Route Handler) or Server Component initialized with createServerClient from @supabase/ssr.
The Supabase middleware (middleware.ts using createMiddlewareClient from @supabase/ssr) seems to work correctly for session refreshing and route protection (redirects work as expected).
The sb-<project_ref>-auth-token cookie is confirmed present in the request headers received by the API route.
Environment variables (SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_PROJECT_REF) are confirmed loaded correctly.
JWT Secret in Supabase project settings is confirmed to exist.
Clearing .next cache and node_modules and performing clean installs did not resolve the issue.
Attempted workarounds using await cookies() before createServerClient did not resolve the AuthSessionMissingError.
Attempted workarounds manually reading the cookie and using the value in Authorization: Bearer header failed (invalid JWT error from Supabase, or JSON parsing errors), indicating the cookie format is not straightforward.