Supabase Common Errors

Overview

Diagnostic guide for Supabase errors across PostgREST (

PGRST*

{ data, error }

data

error

Prerequisites

• @supabase/supabase-js

  installed (

  npm install @supabase/supabase-js

  )

• SUPABASE_URL

  and

  SUPABASE_ANON_KEY

  (or

  SUPABASE_SERVICE_ROLE_KEY

  ) configured
• Access to Supabase Dashboard (for log inspection and SQL Editor)
• Supabase CLI installed for local development (

  npx supabase --version

  )

Instructions

Step 1 — Capture the Error Object

Every Supabase SDK call returns a

{ data, error }

data

error

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
)

// WRONG — data is null when error exists
const { data } = await supabase.from('todos').select('*')
console.log(data.length) // TypeError: Cannot read property 'length' of null

// CORRECT — always check error first
const { data, error } = await supabase.from('todos').select('*')
if (error) {
  console.error(`[${error.code}] ${error.message}`)
  console.error('Details:', error.details)
  console.error('Hint:', error.hint)
  // error.code tells you the layer:
  //   PGRST* = PostgREST (API gateway)
  //   5-digit numeric = PostgreSQL (database)
  //   AuthApiError = Auth service
  //   StorageApiError = Storage service
  return
}
// Safe to use data here
console.log(`Found ${data.length} rows`)

Troubleshooting: If

error

@supabase/supabase-js@2.x

Step 2 — Identify the Error Layer and Code

Match the error code prefix to the correct subsystem, then look up the specific code in the tables below.

PostgREST errors start with

PGRST

42501

23505

AuthApiError

StorageApiError

// Diagnostic helper — paste into your codebase to classify errors automatically
function diagnoseSupabaseError(error: { code?: string; message: string; status?: number }) {
  if (!error) return 'No error'

  if (error.code?.startsWith('PGRST')) {
    return `PostgREST error ${error.code}: ${error.message}\n` +
      'Check: JWT validity, column/table names, query syntax'
  }
  if (error.code && /^\d{5}$/.test(error.code)) {
    return `PostgreSQL error ${error.code}: ${error.message}\n` +
      'Check: RLS policies, constraints, schema migrations'
  }
  if (error.message?.includes('AuthApiError')) {
    return `Auth error: ${error.message}\n` +
      'Check: credentials, email confirmation, token expiry'
  }
  if (error.message?.includes('StorageApiError')) {
    return `Storage error: ${error.message}\n` +
      'Check: bucket exists, RLS on storage.objects, file size limits'
  }
  return `Unknown error: ${JSON.stringify(error)}`
}

Troubleshooting: If the error code is empty or missing, check the HTTP status code on the response. A

401

SUPABASE_ANON_KEY

500

Step 3 — Apply the Fix and Verify

Once you have identified the error code, apply the corresponding fix from the Error Handling table. Then verify the fix by re-running the original operation.

// Example: Fix PGRST301 (JWT expired)
// Before: stale session causes 401
const { data, error } = await supabase.from('todos').select('*')
// error.code === 'PGRST301'

// Fix: refresh the session, then retry
const { error: refreshError } = await supabase.auth.refreshSession()
if (refreshError) {
  // Token is fully invalid — force re-login
  await supabase.auth.signOut()
  console.error('Session expired. Please sign in again.')
  return
}

// Retry the original query
const { data: retryData, error: retryError } = await supabase.from('todos').select('*')
if (retryError) {
  console.error('Still failing after refresh:', retryError.code, retryError.message)
} else {
  console.log('Fixed! Retrieved', retryData.length, 'rows')
}

// Example: Fix 42501 (RLS policy violation)
// Step A: Confirm RLS is the problem using service role client
const adminClient = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // bypasses RLS
  { auth: { autoRefreshToken: false, persistSession: false } }
)
const { data: adminData } = await adminClient.from('todos').select('*')
console.log('Admin sees', adminData?.length, 'rows')  // If this works, RLS is blocking

// Step B: Check which user the JWT resolves to
const { data: { user } } = await supabase.auth.getUser()
console.log('Current auth.uid() =', user?.id)

// Step C: Fix the RLS policy in SQL Editor or migration
/*
  CREATE POLICY "Users can read own todos"
    ON todos FOR SELECT
    USING (auth.uid() = user_id);

  -- Verify with:
  SET request.jwt.claim.sub = '<user-id>';
  SELECT * FROM todos;
*/

// Step D: Retry original query
const { data: fixedData, error: fixedError } = await supabase.from('todos').select('*')
console.log(fixedError ? `Still blocked: ${fixedError.code}` : `Success: ${fixedData.length} rows`)

Troubleshooting: After applying a migration, you may need to reload the PostgREST schema cache. In the Supabase Dashboard, go to Settings > API and click "Reload schema cache", or call

NOTIFY pgrst, 'reload schema'

Output

Deliverables after applying this skill:

• Error identified by code and layer (PostgREST, PostgreSQL, Auth, Storage, Realtime)
• Root cause isolated using the diagnostic helper or manual code inspection
• Fix applied from the Error Handling table and verified against the original failing operation
• Guard code in place (

  if (error)

  checks) preventing silent null-data bugs

Error Handling

PostgREST API Errors (PGRST*)

PGRST301

SUPABASE_ANON_KEY

SUPABASE_ANON_KEY

supabase.auth.refreshSession()

PGRST302

SUPABASE_ANON_KEY

createClient()

PGRST116

.single()

.single()

.maybeSingle()

PGRST200

.eq('col', val)

.eq('col = val')

PGRST204

supabase gen types typescript

PGRST000

PostgreSQL Database Errors (5-digit codes)

42501

23505

.upsert({ onConflict: 'column' })

23503

42P01

supabase db push

\dt

42703

supabase gen types typescript --local > types/supabase.ts

57014

statement_timeout

postgresql.conf

Auth Service Errors

invalid_credentials

Invalid login credentials

email_not_confirmed

Email not confirmed

localhost:54324

user_already_exists

User already registered

signInWithPassword()

signUp()

Token has expired or is invalid

AuthRetryableFetchError

SUPABASE_URL

Storage Errors

Bucket not found

The resource already exists

{ upsert: true }

new row violates row-level security

storage.objects

413 Payload Too Large

file_size_limit

Realtime Errors

CHANNEL_ERROR

supabase_realtime

TIMED_OUT

ALTER PUBLICATION supabase_realtime ADD TABLE your_table;

.subscribe()

Examples

Example 1 — Handling

.single()

on optional data (PGRST116)

// BAD — crashes when user has no profile
const { data: profile } = await supabase
  .from('profiles')
  .select('*')
  .eq('user_id', userId)
  .single()  // throws PGRST116 if no row exists

// GOOD — returns null instead of erroring
const { data: profile, error } = await supabase
  .from('profiles')
  .select('*')
  .eq('user_id', userId)
  .maybeSingle()

if (!profile) {
  // Create a default profile
  const { data: newProfile } = await supabase
    .from('profiles')
    .insert({ user_id: userId, display_name: 'New User' })
    .select()
    .single()
}

Example 2 — Upsert to avoid unique constraint (23505)

// BAD — fails if row already exists
const { error } = await supabase
  .from('user_settings')
  .insert({ user_id: userId, theme: 'dark' })
// error.code === '23505' — unique constraint on user_id

// GOOD — inserts or updates based on conflict column
const { data, error } = await supabase
  .from('user_settings')
  .upsert(
    { user_id: userId, theme: 'dark' },
    { onConflict: 'user_id' }
  )
  .select()
  .single()

Example 3 — Realtime subscription with error handling

const channel = supabase
  .channel('todos-changes')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'todos' },
    (payload) => {
      console.log('Change received:', payload.eventType, payload.new)
    }
  )
  .subscribe((status, err) => {
    switch (status) {
      case 'SUBSCRIBED':
        console.log('Realtime connected')
        break
      case 'CHANNEL_ERROR':
        console.error('Realtime error — is the table in the publication?', err)
        // Fix: ALTER PUBLICATION supabase_realtime ADD TABLE todos;
        break
      case 'TIMED_OUT':
        console.error('Realtime timed out — check network')
        break
      case 'CLOSED':
        console.log('Channel closed')
        break
    }
  })

// Always clean up on unmount / exit
process.on('SIGINT', async () => {
  await supabase.removeChannel(channel)
  process.exit(0)
})

Example 4 — Connection pool exhaustion (PGRST000) in serverless

// BAD — creates a new client per request in serverless (Lambda, Edge Functions)
export async function handler(req: Request) {
  const supabase = createClient(url, key)  // new connection every invocation
  const { data } = await supabase.from('todos').select('*')
  return Response.json(data)
}

// GOOD — reuse client across warm invocations
const supabase = createClient(url, key, {
  auth: { autoRefreshToken: false, persistSession: false }
})

export async function handler(req: Request) {
  const { data, error } = await supabase.from('todos').select('*')
  if (error) {
    if (error.code === 'PGRST000') {
      // Pool exhausted — return 503 so the caller retries
      return new Response('Service temporarily unavailable', { status: 503 })
    }
    return Response.json({ error: error.message }, { status: 400 })
  }
  return Response.json(data)
}

Resources

• Supabase JavaScript SDK Reference
• PostgREST Error Codes
• PostgreSQL Error Codes
• Supabase Auth Error Handling
• RLS Debugging Guide
• Supabase Realtime Troubleshooting
• Supabase Status Page

Next Steps

• Use

  supabase-debug-bundle

  to generate a full diagnostic snapshot when errors persist after applying these fixes.
• Use

  supabase-security-basics

  to audit your RLS policies and prevent

  42501

  errors proactively.
• Use

  supabase-known-pitfalls

  for edge cases and SDK behavior that can cause subtle bugs.
• Use

  supabase-observability

  to set up logging and alerting so you catch errors before users report them.