How to fix flow_state_expired: PKCE flow state has expired in Supabase

The PKCE authorization code expires 5 minutes after the OAuth flow is initiated. Ensure users complete the entire process (click link, authorize, callback) within this window.

If using magic links, advise users to:
- Click the authentication link promptly after requesting it
- Complete any required authorization steps immediately
- Not leave the page idle during the callback process

If the error occurs, the authorization code has expired and cannot be reused. Restart the entire login process:

// User initiates login again
await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: `${window.location.origin}/auth/callback`,
  },
});

For magic links:

await supabase.auth.signInWithOtp({
  email: '[email protected]',
});
// User receives new magic link and must click it promptly

Ensure your OAuth redirect URL is correctly configured in Supabase and matches your application:

1. Go to Supabase dashboard > Authentication > URL Configuration
2. Verify "Redirect URLs" includes your callback URL exactly as it appears in your app
3. For local development: http://localhost:3000/auth/callback
4. For production: https://yourdomain.com/auth/callback

Misconfigured URLs can cause unnecessary delays reaching the callback endpoint.

For OAuth providers (Google, GitHub, etc.), also verify:
- OAuth client ID and secret are correct
- Authorized redirect URIs include your Supabase callback URL

If building a server-side rendered (SSR) application, use the @supabase/ssr package which handles PKCE flow and session management automatically:

npm install @supabase/ssr

import { createServerClient } from '@supabase/ssr';

const supabase = createServerClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
  {
    cookies: {
      getAll() { /* ... */ },
      setAll() { /* ... */ },
    },
  }
);

This package:
- Uses PKCE flow by default
- Automatically handles state parameter storage in cookies
- Manages session tokens securely
- Handles callback exchange server-side

When handling the OAuth callback, ensure you exchange the code within the 5-minute window:

// In your callback route handler (/auth/callback)
const { data, error } = await supabase.auth.exchangeCodeForSession(code);

if (error) {
  // Log specific error
  console.error('Code exchange failed:', error.message);
  // Redirect user back to login
  return redirect('/login');
}

// Session is now valid, redirect to dashboard
return redirect('/dashboard');

Ensure:
- The callback handler executes immediately upon redirect
- No delays or middleware interferes with code exchange
- The code is extracted from the URL query parameter and passed correctly