Supabase Auth Error Codes: Fixes + TS Cheat Sheet (2026)

const { error } = await supabase.auth.signInWithPassword({ email, password });
if (error) {
  setError('Something went wrong. Please try again.');
}

// lib/auth-errors.ts
import type { AuthError } from '@supabase/supabase-js';
 
export const AUTH_ERROR_CODES = [
  'invalid_credentials',
  'email_not_confirmed',
  'user_not_found',
  'weak_password',
  'same_password',
  'email_address_invalid',
  'over_email_send_rate_limit',
  'over_request_rate_limit',
  'signup_disabled',
  'email_exists',
  'phone_exists',
  'user_already_exists',
  'session_expired',
  'refresh_token_not_found',
  'otp_expired',
  'captcha_failed',
] as const;
 
export type AuthErrorCode = typeof AUTH_ERROR_CODES[number];
 
export type AuthUserError = {
  /** Message safe to show end-users */
  message: string;
  /** Which form field to highlight, if any */
  field?: 'email' | 'password' | 'newPassword' | 'otp';
  /** Optional CTA hint for the UI */
  action?: 'resend_confirmation' | 'reset_password' | 'wait' | 'contact_support';
  /** Seconds to wait before retry, when known */
  retryAfter?: number;
};
 
const ERRORS: Record<AuthErrorCode, AuthUserError> = {
  invalid_credentials: {
    // SECURITY: never disclose whether the email exists.
    message: 'The email or password is incorrect.',
    field: 'password',
  },
  email_not_confirmed: {
    message: 'Please confirm your email before signing in.',
    field: 'email',
    action: 'resend_confirmation',
  },
  user_not_found: {
    // Same message as invalid_credentials — do not leak account existence.
    message: 'The email or password is incorrect.',
    field: 'email',
  },
  weak_password: {
    message:
      'Password must be at least 8 characters and include a number and a symbol.',
    field: 'password',
  },
  same_password: {
    message: 'Your new password must be different from your current password.',
    field: 'newPassword',
  },
  email_address_invalid: {
    message: 'That email address looks invalid. Double-check the format.',
    field: 'email',
  },
  over_email_send_rate_limit: {
    message: 'Too many requests. Try again in a minute.',
    action: 'wait',
    retryAfter: 60,
  },
  over_request_rate_limit: {
    message: 'You’re going too fast. Please wait a moment.',
    action: 'wait',
    retryAfter: 30,
  },
  signup_disabled: {
    message: 'New signups are currently disabled.',
    action: 'contact_support',
  },
  email_exists: {
    message: 'An account with this email already exists. Try signing in.',
    field: 'email',
    action: 'reset_password',
  },
  phone_exists: {
    message: 'An account with this phone number already exists.',
    field: 'email',
  },
  user_already_exists: {
    message: 'An account with this email already exists. Try signing in.',
    field: 'email',
    action: 'reset_password',
  },
  session_expired: {
    message: 'Your session expired. Please sign in again.',
  },
  refresh_token_not_found: {
    message: 'Your session expired. Please sign in again.',
  },
  otp_expired: {
    message: 'The code has expired. Request a new one.',
    field: 'otp',
  },
  captcha_failed: {
    message: 'Captcha verification failed. Please try again.',
  },
};
 
const FALLBACK: AuthUserError = {
  message: 'Something went wrong. Please try again.',
};
 
/**
 * Translate any Supabase AuthError (or unknown error) into a user-facing
 * AuthUserError. Logs the raw error for observability.
 */
export function toUserError(error: unknown): AuthUserError {
  if (!error) return FALLBACK;
 
  const authError = error as Partial<AuthError>;
  const code = authError.code as AuthErrorCode | undefined;
 
  if (code && code in ERRORS) {
    return ERRORS[code];
  }
 
  // Unknown code: log for triage, show fallback
  console.error('[auth] unhandled error', {
    code: authError.code,
    status: authError.status,
    message: authError.message,
  });
 
  return FALLBACK;
}

// app/sign-in/SignInForm.tsx
'use client';
import { useState } from 'react';
import { createBrowserClient } from '@supabase/ssr';
import { toUserError, type AuthUserError } from '@/lib/auth-errors';
 
export function SignInForm() {
  const [authError, setAuthError] = useState<AuthUserError | null>(null);
  const [isPending, setPending] = useState(false);
 
  async function onSubmit(formData: FormData) {
    setPending(true);
    setAuthError(null);
 
    const supabase = createBrowserClient(
      process.env.NEXT_PUBLIC_SUPABASE_URL!,
      process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
    );
 
    const { error } = await supabase.auth.signInWithPassword({
      email: String(formData.get('email')),
      password: String(formData.get('password')),
    });
 
    if (error) {
      setAuthError(toUserError(error));
    }
    setPending(false);
  }
 
  return (
    <form action={onSubmit}>
      <label>
        Email
        <input
          name="email"
          type="email"
          aria-invalid={authError?.field === 'email'}
          required
        />
      </label>
      <label>
        Password
        <input
          name="password"
          type="password"
          aria-invalid={authError?.field === 'password'}
          required
        />
      </label>
 
      {authError && (
        <div role="alert" className="text-red-600">
          {authError.message}
          {authError.action === 'resend_confirmation' && (
            <button type="button" onClick={resendConfirmation}>
              Resend confirmation email
            </button>
          )}
          {authError.action === 'reset_password' && (
            <a href="/reset-password">Reset password</a>
          )}
        </div>
      )}
 
      <button type="submit" disabled={isPending}>
        {isPending ? 'Signing in…' : 'Sign in'}
      </button>
    </form>
  );
}
 
async function resendConfirmation() {
  // call your resend route
}

{authError?.action === 'wait' && (
  <Countdown seconds={authError.retryAfter ?? 60} />
)}

// app/api/auth/sign-in/route.ts
import { NextResponse } from 'next/server';
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';
import { toUserError } from '@/lib/auth-errors';
 
export async function POST(req: Request) {
  const { email, password } = await req.json();
  const cookieStore = await cookies();
  const supabase = createServerClient(/* ... */);
 
  const { error } = await supabase.auth.signInWithPassword({ email, password });
 
  if (error) {
    const userError = toUserError(error);
    return NextResponse.json({ error: userError }, { status: 400 });
  }
 
  return NextResponse.json({ ok: true });
}