[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M796DX5MJ8V0JC8N254APYC9":3,"skill-same:01M796DX5MJ8V0JC8N254APYC9":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":37,"commitSha":38,"skillDirectory":39,"forksCount":40,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":43,"ownerDescription":44,"updatedAt":45,"install":46,"resources":59},"01M796DX5MJ8V0JC8N254APYC9","supabase-common-errors",null,"Diagnose and fix Supabase errors across PostgREST, PostgreSQL, Auth, Storage, and Realtime.\nUse when encountering error codes like PGRST301, 42501, 23505, or auth failures.\nUse when debugging failed queries, RLS policy violations, or HTTP 4xx\u002F5xx responses.\nTrigger with \"supabase error\", \"fix supabase\", \"PGRST\", \"supabase 403\", \"RLS not working\",\n\"supabase auth error\", \"unique constraint\", \"foreign key violation\".","jukeyman\u002Fjukeyman-skills","jukeyman","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142960420?v=4","01M78FR4Y3DHMMCBCC0GXXNB3F","RICK JEFFERSON","01M78FR4Z8RVQRAD31Y5J7V6EB",1,"MIT","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--supabase-pack--supabase-common-errors\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: supabase-common-errors\ndescription: |\n  Diagnose and fix Supabase errors across PostgREST, PostgreSQL, Auth, Storage, and Realtime.\n  Use when encountering error codes like PGRST301, 42501, 23505, or auth failures.\n  Use when debugging failed queries, RLS policy violations, or HTTP 4xx\u002F5xx responses.\n  Trigger with \"supabase error\", \"fix supabase\", \"PGRST\", \"supabase 403\", \"RLS not working\",\n  \"supabase auth error\", \"unique constraint\", \"foreign key violation\".\nallowed-tools: Read, Grep, Bash(curl:*), Bash(supabase:*), Bash(npx:*)\nversion: 1.0.0\nlicense: MIT\nauthor: Jeremy Longshore \u003Cjeremy@intentsolutions.io>\ncompatible-with: claude-code, codex, openclaw\ntags: [saas, supabase, debugging, errors, postgrest, rls, auth]\n---\n\n# Supabase Common Errors\n\n## Overview\n\nDiagnostic guide for Supabase errors across PostgREST (`PGRST*`), PostgreSQL (numeric codes), Auth, Storage, and Realtime. Identify the error layer, trace the root cause, and apply the correct fix — every SDK call returns `{ data, error }` where `data` is null when `error` exists.\n\n## Prerequisites\n\n- `@supabase\u002Fsupabase-js` installed (`npm install @supabase\u002Fsupabase-js`)\n- `SUPABASE_URL` and `SUPABASE_ANON_KEY` (or `SUPABASE_SERVICE_ROLE_KEY`) configured\n- Access to Supabase Dashboard (for log inspection and SQL Editor)\n- Supabase CLI installed for local development (`npx supabase --version`)\n\n## Instructions\n\n### Step 1 — Capture the Error Object\n\nEvery Supabase SDK call returns a `{ data, error }` tuple. Never assume `data` exists — always check `error` first.\n\n```typescript\nimport { createClient } from '@supabase\u002Fsupabase-js'\n\nconst supabase = createClient(\n  process.env.SUPABASE_URL!,\n  process.env.SUPABASE_ANON_KEY!\n)\n\n\u002F\u002F WRONG — data is null when error exists\nconst { data } = await supabase.from('todos').select('*')\nconsole.log(data.length) \u002F\u002F TypeError: Cannot read property 'length' of null\n\n\u002F\u002F CORRECT — always check error first\nconst { data, error } = await supabase.from('todos').select('*')\nif (error) {\n  console.error(`[${error.code}] ${error.message}`)\n  console.error('Details:', error.details)\n  console.error('Hint:', error.hint)\n  \u002F\u002F error.code tells you the layer:\n  \u002F\u002F   PGRST* = PostgREST (API gateway)\n  \u002F\u002F   5-digit numeric = PostgreSQL (database)\n  \u002F\u002F   AuthApiError = Auth service\n  \u002F\u002F   StorageApiError = Storage service\n  return\n}\n\u002F\u002F Safe to use data here\nconsole.log(`Found ${data.length} rows`)\n```\n\n**Troubleshooting:** If `error` is undefined (not null), you may be using an older SDK version. Upgrade to `@supabase\u002Fsupabase-js@2.x` or later.\n\n### Step 2 — Identify the Error Layer and Code\n\nMatch the error code prefix to the correct subsystem, then look up the specific code in the tables below.\n\n**PostgREST errors** start with `PGRST` and correspond to API-layer issues (JWT, query parsing, schema).\n**PostgreSQL errors** are 5-character codes (e.g., `42501`, `23505`) from the database engine.\n**Auth errors** come as `AuthApiError` with a human-readable message.\n**Storage errors** come as `StorageApiError` with an HTTP status.\n\n```typescript\n\u002F\u002F Diagnostic helper — paste into your codebase to classify errors automatically\nfunction diagnoseSupabaseError(error: { code?: string; message: string; status?: number }) {\n  if (!error) return 'No error'\n\n  if (error.code?.startsWith('PGRST')) {\n    return `PostgREST error ${error.code}: ${error.message}\\n` +\n      'Check: JWT validity, column\u002Ftable names, query syntax'\n  }\n  if (error.code && \u002F^\\d{5}$\u002F.test(error.code)) {\n    return `PostgreSQL error ${error.code}: ${error.message}\\n` +\n      'Check: RLS policies, constraints, schema migrations'\n  }\n  if (error.message?.includes('AuthApiError')) {\n    return `Auth error: ${error.message}\\n` +\n      'Check: credentials, email confirmation, token expiry'\n  }\n  if (error.message?.includes('StorageApiError')) {\n    return `Storage error: ${error.message}\\n` +\n      'Check: bucket exists, RLS on storage.objects, file size limits'\n  }\n  return `Unknown error: ${JSON.stringify(error)}`\n}\n```\n\n**Troubleshooting:** If the error code is empty or missing, check the HTTP status code on the response. A `401` without a code usually means `SUPABASE_ANON_KEY` is wrong or missing. A `500` without a code usually means a database function threw an unhandled exception.\n\n### Step 3 — Apply the Fix and Verify\n\nOnce 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.\n\n```typescript\n\u002F\u002F Example: Fix PGRST301 (JWT expired)\n\u002F\u002F Before: stale session causes 401\nconst { data, error } = await supabase.from('todos').select('*')\n\u002F\u002F error.code === 'PGRST301'\n\n\u002F\u002F Fix: refresh the session, then retry\nconst { error: refreshError } = await supabase.auth.refreshSession()\nif (refreshError) {\n  \u002F\u002F Token is fully invalid — force re-login\n  await supabase.auth.signOut()\n  console.error('Session expired. Please sign in again.')\n  return\n}\n\n\u002F\u002F Retry the original query\nconst { data: retryData, error: retryError } = await supabase.from('todos').select('*')\nif (retryError) {\n  console.error('Still failing after refresh:', retryError.code, retryError.message)\n} else {\n  console.log('Fixed! Retrieved', retryData.length, 'rows')\n}\n```\n\n```typescript\n\u002F\u002F Example: Fix 42501 (RLS policy violation)\n\u002F\u002F Step A: Confirm RLS is the problem using service role client\nconst adminClient = createClient(\n  process.env.SUPABASE_URL!,\n  process.env.SUPABASE_SERVICE_ROLE_KEY!,  \u002F\u002F bypasses RLS\n  { auth: { autoRefreshToken: false, persistSession: false } }\n)\nconst { data: adminData } = await adminClient.from('todos').select('*')\nconsole.log('Admin sees', adminData?.length, 'rows')  \u002F\u002F If this works, RLS is blocking\n\n\u002F\u002F Step B: Check which user the JWT resolves to\nconst { data: { user } } = await supabase.auth.getUser()\nconsole.log('Current auth.uid() =', user?.id)\n\n\u002F\u002F Step C: Fix the RLS policy in SQL Editor or migration\n\u002F*\n  CREATE POLICY \"Users can read own todos\"\n    ON todos FOR SELECT\n    USING (auth.uid() = user_id);\n\n  -- Verify with:\n  SET request.jwt.claim.sub = '\u003Cuser-id>';\n  SELECT * FROM todos;\n*\u002F\n\n\u002F\u002F Step D: Retry original query\nconst { data: fixedData, error: fixedError } = await supabase.from('todos').select('*')\nconsole.log(fixedError ? `Still blocked: ${fixedError.code}` : `Success: ${fixedData.length} rows`)\n```\n\n**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'` in SQL.\n\n## Output\n\nDeliverables after applying this skill:\n\n- Error identified by code and layer (PostgREST, PostgreSQL, Auth, Storage, Realtime)\n- Root cause isolated using the diagnostic helper or manual code inspection\n- Fix applied from the Error Handling table and verified against the original failing operation\n- Guard code in place (`if (error)` checks) preventing silent null-data bugs\n\n## Error Handling\n\n### PostgREST API Errors (PGRST*)\n\n| Code | HTTP | Meaning | Root Cause | Fix |\n|------|------|---------|------------|-----|\n| `PGRST301` | 401 | JWT expired or invalid | `SUPABASE_ANON_KEY` is wrong, or the user session expired | Verify `SUPABASE_ANON_KEY` matches the project; call `supabase.auth.refreshSession()` |\n| `PGRST302` | 401 | Missing Authorization header | Client created without a key, or middleware stripped the header | Pass `SUPABASE_ANON_KEY` to `createClient()`; check proxy\u002FCDN config |\n| `PGRST116` | 406 | No rows returned for `.single()` | Query matched 0 rows but `.single()` expects exactly 1 | Use `.maybeSingle()` for optional lookups, or check filters |\n| `PGRST200` | 400 | Invalid query parameters | Malformed filter, bad operator, or invalid column reference | Check filter syntax: `.eq('col', val)` not `.eq('col = val')` |\n| `PGRST204` | 400 | Column not found | Column name doesn't exist in the table or view | Verify column exists with `supabase gen types typescript`; check for typos |\n| `PGRST000` | 503 | Connection pool exhausted | Too many concurrent connections from serverless functions | Enable pgBouncer (Supavisor) in project settings; reduce connection count |\n\n### PostgreSQL Database Errors (5-digit codes)\n\n| Code | Meaning | Root Cause | Fix |\n|------|---------|------------|-----|\n| `42501` | RLS policy violation | Row-level security is blocking the operation for this user | Add or fix the RLS policy; test with service role to confirm |\n| `23505` | Unique constraint violation | INSERT\u002FUPDATE conflicts with an existing row | Use `.upsert({ onConflict: 'column' })` or check existence first |\n| `23503` | Foreign key violation | Referenced row doesn't exist in the parent table | Insert the parent row first, or check the foreign key value |\n| `42P01` | Table or relation doesn't exist | Migration not applied, or wrong schema | Run `supabase db push`; verify schema with `\\dt` in SQL Editor |\n| `42703` | Column doesn't exist | Schema out of sync with code | Regenerate types: `supabase gen types typescript --local > types\u002Fsupabase.ts` |\n| `57014` | Query cancelled (statement timeout) | Query took longer than `statement_timeout` | Add indexes; simplify the query; increase timeout in `postgresql.conf` |\n\n### Auth Service Errors\n\n| Error Message | Cause | Fix |\n|---------------|-------|-----|\n| `invalid_credentials` \u002F `Invalid login credentials` | Wrong email or password | Verify credentials; check if email is confirmed |\n| `email_not_confirmed` \u002F `Email not confirmed` | User hasn't clicked confirmation link | Check inbox\u002Fspam; for local dev check Inbucket at `localhost:54324` |\n| `user_already_exists` \u002F `User already registered` | Duplicate sign-up | Call `signInWithPassword()` instead of `signUp()` |\n| `Token has expired or is invalid` | Stale magic link or OTP | Request a new magic link or OTP; links expire after 5 minutes by default |\n| `AuthRetryableFetchError` | Network failure reaching Auth service | Retry with backoff; verify `SUPABASE_URL` is correct and reachable |\n\n### Storage Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `Bucket not found` | Bucket name is wrong or bucket doesn't exist | Create the bucket in Dashboard or via migration SQL |\n| `The resource already exists` | Uploading to a path that already has a file | Pass `{ upsert: true }` in upload options to overwrite |\n| `new row violates row-level security` | Storage RLS blocking the upload\u002Fdownload | Add a policy on `storage.objects` for the operation (INSERT, SELECT, DELETE) |\n| `413 Payload Too Large` | File exceeds the bucket's size limit | Increase `file_size_limit` on the bucket, or use TUS resumable upload for large files |\n\n### Realtime Errors\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `CHANNEL_ERROR` on subscribe | Realtime not enabled for the table | Dashboard > Database > Replication > enable the table; or add it to `supabase_realtime` publication |\n| `TIMED_OUT` on subscribe | Network issue or firewall blocking WebSocket | Check that port 443 WebSocket connections are allowed |\n| No events received | Table not in Realtime publication | Run: `ALTER PUBLICATION supabase_realtime ADD TABLE your_table;` |\n| Events stop after deploy | Schema change drops Realtime connections | Clients auto-reconnect; ensure `.subscribe()` handles reconnection |\n\n## Examples\n\n### Example 1 — Handling `.single()` on optional data (PGRST116)\n\n```typescript\n\u002F\u002F BAD — crashes when user has no profile\nconst { data: profile } = await supabase\n  .from('profiles')\n  .select('*')\n  .eq('user_id', userId)\n  .single()  \u002F\u002F throws PGRST116 if no row exists\n\n\u002F\u002F GOOD — returns null instead of erroring\nconst { data: profile, error } = await supabase\n  .from('profiles')\n  .select('*')\n  .eq('user_id', userId)\n  .maybeSingle()\n\nif (!profile) {\n  \u002F\u002F Create a default profile\n  const { data: newProfile } = await supabase\n    .from('profiles')\n    .insert({ user_id: userId, display_name: 'New User' })\n    .select()\n    .single()\n}\n```\n\n### Example 2 — Upsert to avoid unique constraint (23505)\n\n```typescript\n\u002F\u002F BAD — fails if row already exists\nconst { error } = await supabase\n  .from('user_settings')\n  .insert({ user_id: userId, theme: 'dark' })\n\u002F\u002F error.code === '23505' — unique constraint on user_id\n\n\u002F\u002F GOOD — inserts or updates based on conflict column\nconst { data, error } = await supabase\n  .from('user_settings')\n  .upsert(\n    { user_id: userId, theme: 'dark' },\n    { onConflict: 'user_id' }\n  )\n  .select()\n  .single()\n```\n\n### Example 3 — Realtime subscription with error handling\n\n```typescript\nconst channel = supabase\n  .channel('todos-changes')\n  .on(\n    'postgres_changes',\n    { event: '*', schema: 'public', table: 'todos' },\n    (payload) => {\n      console.log('Change received:', payload.eventType, payload.new)\n    }\n  )\n  .subscribe((status, err) => {\n    switch (status) {\n      case 'SUBSCRIBED':\n        console.log('Realtime connected')\n        break\n      case 'CHANNEL_ERROR':\n        console.error('Realtime error — is the table in the publication?', err)\n        \u002F\u002F Fix: ALTER PUBLICATION supabase_realtime ADD TABLE todos;\n        break\n      case 'TIMED_OUT':\n        console.error('Realtime timed out — check network')\n        break\n      case 'CLOSED':\n        console.log('Channel closed')\n        break\n    }\n  })\n\n\u002F\u002F Always clean up on unmount \u002F exit\nprocess.on('SIGINT', async () => {\n  await supabase.removeChannel(channel)\n  process.exit(0)\n})\n```\n\n### Example 4 — Connection pool exhaustion (PGRST000) in serverless\n\n```typescript\n\u002F\u002F BAD — creates a new client per request in serverless (Lambda, Edge Functions)\nexport async function handler(req: Request) {\n  const supabase = createClient(url, key)  \u002F\u002F new connection every invocation\n  const { data } = await supabase.from('todos').select('*')\n  return Response.json(data)\n}\n\n\u002F\u002F GOOD — reuse client across warm invocations\nconst supabase = createClient(url, key, {\n  auth: { autoRefreshToken: false, persistSession: false }\n})\n\nexport async function handler(req: Request) {\n  const { data, error } = await supabase.from('todos').select('*')\n  if (error) {\n    if (error.code === 'PGRST000') {\n      \u002F\u002F Pool exhausted — return 503 so the caller retries\n      return new Response('Service temporarily unavailable', { status: 503 })\n    }\n    return Response.json({ error: error.message }, { status: 400 })\n  }\n  return Response.json(data)\n}\n```\n\n## Resources\n\n- [Supabase JavaScript SDK Reference](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Freference\u002Fjavascript\u002Fintroduction)\n- [PostgREST Error Codes](https:\u002F\u002Fpostgrest.org\u002Fen\u002Fstable\u002Freferences\u002Ferrors.html)\n- [PostgreSQL Error Codes](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Ferrcodes-appendix.html)\n- [Supabase Auth Error Handling](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Freference\u002Fjavascript\u002Fauth-error-codes)\n- [RLS Debugging Guide](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Fdatabase\u002Fpostgres\u002Frow-level-security)\n- [Supabase Realtime Troubleshooting](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Frealtime\u002Ftroubleshooting)\n- [Supabase Status Page](https:\u002F\u002Fstatus.supabase.com)\n\n## Next Steps\n\n- Use `supabase-debug-bundle` to generate a full diagnostic snapshot when errors persist after applying these fixes.\n- Use `supabase-security-basics` to audit your RLS policies and prevent `42501` errors proactively.\n- Use `supabase-known-pitfalls` for edge cases and SDK behavior that can cause subtle bugs.\n- Use `supabase-observability` to set up logging and alerting so you catch errors before users report them.\n","# Supabase Common Errors\n\n## Overview\n\nDiagnostic guide for Supabase errors across PostgREST (`PGRST*`), PostgreSQL (numeric codes), Auth, Storage, and Realtime. Identify the error layer, trace the root cause, and apply the correct fix — every SDK call returns `{ data, error }` where `data` is null when `error` exists.\n\n## Prerequisites\n\n- `@supabase\u002Fsupabase-js` installed (`npm install @supabase\u002Fsupabase-js`)\n- `SUPABASE_URL` and `SUPABASE_ANON_KEY` (or `SUPABASE_SERVICE_ROLE_KEY`) configured\n- Access to Supabase Dashboard (for log inspection and SQL Editor)\n- Supabase CLI installed for local development (`npx supabase --version`)\n\n## Instructions\n\n### Step 1 — Capture the Error Object\n\nEvery Supabase SDK call returns a `{ data, error }` tuple. Never assume `data` exists — always check `error` first.\n\n```typescript\nimport { createClient } from '@supabase\u002Fsupabase-js'\n\nconst supabase = createClient(\n  process.env.SUPABASE_URL!,\n  process.env.SUPABASE_ANON_KEY!\n)\n\n\u002F\u002F WRONG — data is null when error exists\nconst { data } = await supabase.from('todos').select('*')\nconsole.log(data.length) \u002F\u002F TypeError: Cannot read property 'length' of null\n\n\u002F\u002F CORRECT — always check error first\nconst { data, error } = await supabase.from('todos').select('*')\nif (error) {\n  console.error(`[${error.code}] ${error.message}`)\n  console.error('Details:', error.details)\n  console.error('Hint:', error.hint)\n  \u002F\u002F error.code tells you the layer:\n  \u002F\u002F   PGRST* = PostgREST (API gateway)\n  \u002F\u002F   5-digit numeric = PostgreSQL (database)\n  \u002F\u002F   AuthApiError = Auth service\n  \u002F\u002F   StorageApiError = Storage service\n  return\n}\n\u002F\u002F Safe to use data here\nconsole.log(`Found ${data.length} rows`)\n```\n\n**Troubleshooting:** If `error` is undefined (not null), you may be using an older SDK version. Upgrade to `@supabase\u002Fsupabase-js@2.x` or later.\n\n### Step 2 — Identify the Error Layer and Code\n\nMatch the error code prefix to the correct subsystem, then look up the specific code in the tables below.\n\n**PostgREST errors** start with `PGRST` and correspond to API-layer issues (JWT, query parsing, schema).\n**PostgreSQL errors** are 5-character codes (e.g., `42501`, `23505`) from the database engine.\n**Auth errors** come as `AuthApiError` with a human-readable message.\n**Storage errors** come as `StorageApiError` with an HTTP status.\n\n```typescript\n\u002F\u002F Diagnostic helper — paste into your codebase to classify errors automatically\nfunction diagnoseSupabaseError(error: { code?: string; message: string; status?: number }) {\n  if (!error) return 'No error'\n\n  if (error.code?.startsWith('PGRST')) {\n    return `PostgREST error ${error.code}: ${error.message}\\n` +\n      'Check: JWT validity, column\u002Ftable names, query syntax'\n  }\n  if (error.code && \u002F^\\d{5}$\u002F.test(error.code)) {\n    return `PostgreSQL error ${error.code}: ${error.message}\\n` +\n      'Check: RLS policies, constraints, schema migrations'\n  }\n  if (error.message?.includes('AuthApiError')) {\n    return `Auth error: ${error.message}\\n` +\n      'Check: credentials, email confirmation, token expiry'\n  }\n  if (error.message?.includes('StorageApiError')) {\n    return `Storage error: ${error.message}\\n` +\n      'Check: bucket exists, RLS on storage.objects, file size limits'\n  }\n  return `Unknown error: ${JSON.stringify(error)}`\n}\n```\n\n**Troubleshooting:** If the error code is empty or missing, check the HTTP status code on the response. A `401` without a code usually means `SUPABASE_ANON_KEY` is wrong or missing. A `500` without a code usually means a database function threw an unhandled exception.\n\n### Step 3 — Apply the Fix and Verify\n\nOnce 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.\n\n```typescript\n\u002F\u002F Example: Fix PGRST301 (JWT expired)\n\u002F\u002F Before: stale session causes 401\nconst { data, error } = await supabase.from('todos').select('*')\n\u002F\u002F error.code === 'PGRST301'\n\n\u002F\u002F Fix: refresh the session, then retry\nconst { error: refreshError } = await supabase.auth.refreshSession()\nif (refreshError) {\n  \u002F\u002F Token is fully invalid — force re-login\n  await supabase.auth.signOut()\n  console.error('Session expired. Please sign in again.')\n  return\n}\n\n\u002F\u002F Retry the original query\nconst { data: retryData, error: retryError } = await supabase.from('todos').select('*')\nif (retryError) {\n  console.error('Still failing after refresh:', retryError.code, retryError.message)\n} else {\n  console.log('Fixed! Retrieved', retryData.length, 'rows')\n}\n```\n\n```typescript\n\u002F\u002F Example: Fix 42501 (RLS policy violation)\n\u002F\u002F Step A: Confirm RLS is the problem using service role client\nconst adminClient = createClient(\n  process.env.SUPABASE_URL!,\n  process.env.SUPABASE_SERVICE_ROLE_KEY!,  \u002F\u002F bypasses RLS\n  { auth: { autoRefreshToken: false, persistSession: false } }\n)\nconst { data: adminData } = await adminClient.from('todos').select('*')\nconsole.log('Admin sees', adminData?.length, 'rows')  \u002F\u002F If this works, RLS is blocking\n\n\u002F\u002F Step B: Check which user the JWT resolves to\nconst { data: { user } } = await supabase.auth.getUser()\nconsole.log('Current auth.uid() =', user?.id)\n\n\u002F\u002F Step C: Fix the RLS policy in SQL Editor or migration\n\u002F*\n  CREATE POLICY \"Users can read own todos\"\n    ON todos FOR SELECT\n    USING (auth.uid() = user_id);\n\n  -- Verify with:\n  SET request.jwt.claim.sub = '\u003Cuser-id>';\n  SELECT * FROM todos;\n*\u002F\n\n\u002F\u002F Step D: Retry original query\nconst { data: fixedData, error: fixedError } = await supabase.from('todos').select('*')\nconsole.log(fixedError ? `Still blocked: ${fixedError.code}` : `Success: ${fixedData.length} rows`)\n```\n\n**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'` in SQL.\n\n## Output\n\nDeliverables after applying this skill:\n\n- Error identified by code and layer (PostgREST, PostgreSQL, Auth, Storage, Realtime)\n- Root cause isolated using the diagnostic helper or manual code inspection\n- Fix applied from the Error Handling table and verified against the original failing operation\n- Guard code in place (`if (error)` checks) preventing silent null-data bugs\n\n## Error Handling\n\n### PostgREST API Errors (PGRST*)\n\n| Code | HTTP | Meaning | Root Cause | Fix |\n|------|------|---------|------------|-----|\n| `PGRST301` | 401 | JWT expired or invalid | `SUPABASE_ANON_KEY` is wrong, or the user session expired | Verify `SUPABASE_ANON_KEY` matches the project; call `supabase.auth.refreshSession()` |\n| `PGRST302` | 401 | Missing Authorization header | Client created without a key, or middleware stripped the header | Pass `SUPABASE_ANON_KEY` to `createClient()`; check proxy\u002FCDN config |\n| `PGRST116` | 406 | No rows returned for `.single()` | Query matched 0 rows but `.single()` expects exactly 1 | Use `.maybeSingle()` for optional lookups, or check filters |\n| `PGRST200` | 400 | Invalid query parameters | Malformed filter, bad operator, or invalid column reference | Check filter syntax: `.eq('col', val)` not `.eq('col = val')` |\n| `PGRST204` | 400 | Column not found | Column name doesn't exist in the table or view | Verify column exists with `supabase gen types typescript`; check for typos |\n| `PGRST000` | 503 | Connection pool exhausted | Too many concurrent connections from serverless functions | Enable pgBouncer (Supavisor) in project settings; reduce connection count |\n\n### PostgreSQL Database Errors (5-digit codes)\n\n| Code | Meaning | Root Cause | Fix |\n|------|---------|------------|-----|\n| `42501` | RLS policy violation | Row-level security is blocking the operation for this user | Add or fix the RLS policy; test with service role to confirm |\n| `23505` | Unique constraint violation | INSERT\u002FUPDATE conflicts with an existing row | Use `.upsert({ onConflict: 'column' })` or check existence first |\n| `23503` | Foreign key violation | Referenced row doesn't exist in the parent table | Insert the parent row first, or check the foreign key value |\n| `42P01` | Table or relation doesn't exist | Migration not applied, or wrong schema | Run `supabase db push`; verify schema with `\\dt` in SQL Editor |\n| `42703` | Column doesn't exist | Schema out of sync with code | Regenerate types: `supabase gen types typescript --local > types\u002Fsupabase.ts` |\n| `57014` | Query cancelled (statement timeout) | Query took longer than `statement_timeout` | Add indexes; simplify the query; increase timeout in `postgresql.conf` |\n\n### Auth Service Errors\n\n| Error Message | Cause | Fix |\n|---------------|-------|-----|\n| `invalid_credentials` \u002F `Invalid login credentials` | Wrong email or password | Verify credentials; check if email is confirmed |\n| `email_not_confirmed` \u002F `Email not confirmed` | User hasn't clicked confirmation link | Check inbox\u002Fspam; for local dev check Inbucket at `localhost:54324` |\n| `user_already_exists` \u002F `User already registered` | Duplicate sign-up | Call `signInWithPassword()` instead of `signUp()` |\n| `Token has expired or is invalid` | Stale magic link or OTP | Request a new magic link or OTP; links expire after 5 minutes by default |\n| `AuthRetryableFetchError` | Network failure reaching Auth service | Retry with backoff; verify `SUPABASE_URL` is correct and reachable |\n\n### Storage Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `Bucket not found` | Bucket name is wrong or bucket doesn't exist | Create the bucket in Dashboard or via migration SQL |\n| `The resource already exists` | Uploading to a path that already has a file | Pass `{ upsert: true }` in upload options to overwrite |\n| `new row violates row-level security` | Storage RLS blocking the upload\u002Fdownload | Add a policy on `storage.objects` for the operation (INSERT, SELECT, DELETE) |\n| `413 Payload Too Large` | File exceeds the bucket's size limit | Increase `file_size_limit` on the bucket, or use TUS resumable upload for large files |\n\n### Realtime Errors\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `CHANNEL_ERROR` on subscribe | Realtime not enabled for the table | Dashboard > Database > Replication > enable the table; or add it to `supabase_realtime` publication |\n| `TIMED_OUT` on subscribe | Network issue or firewall blocking WebSocket | Check that port 443 WebSocket connections are allowed |\n| No events received | Table not in Realtime publication | Run: `ALTER PUBLICATION supabase_realtime ADD TABLE your_table;` |\n| Events stop after deploy | Schema change drops Realtime connections | Clients auto-reconnect; ensure `.subscribe()` handles reconnection |\n\n## Examples\n\n### Example 1 — Handling `.single()` on optional data (PGRST116)\n\n```typescript\n\u002F\u002F BAD — crashes when user has no profile\nconst { data: profile } = await supabase\n  .from('profiles')\n  .select('*')\n  .eq('user_id', userId)\n  .single()  \u002F\u002F throws PGRST116 if no row exists\n\n\u002F\u002F GOOD — returns null instead of erroring\nconst { data: profile, error } = await supabase\n  .from('profiles')\n  .select('*')\n  .eq('user_id', userId)\n  .maybeSingle()\n\nif (!profile) {\n  \u002F\u002F Create a default profile\n  const { data: newProfile } = await supabase\n    .from('profiles')\n    .insert({ user_id: userId, display_name: 'New User' })\n    .select()\n    .single()\n}\n```\n\n### Example 2 — Upsert to avoid unique constraint (23505)\n\n```typescript\n\u002F\u002F BAD — fails if row already exists\nconst { error } = await supabase\n  .from('user_settings')\n  .insert({ user_id: userId, theme: 'dark' })\n\u002F\u002F error.code === '23505' — unique constraint on user_id\n\n\u002F\u002F GOOD — inserts or updates based on conflict column\nconst { data, error } = await supabase\n  .from('user_settings')\n  .upsert(\n    { user_id: userId, theme: 'dark' },\n    { onConflict: 'user_id' }\n  )\n  .select()\n  .single()\n```\n\n### Example 3 — Realtime subscription with error handling\n\n```typescript\nconst channel = supabase\n  .channel('todos-changes')\n  .on(\n    'postgres_changes',\n    { event: '*', schema: 'public', table: 'todos' },\n    (payload) => {\n      console.log('Change received:', payload.eventType, payload.new)\n    }\n  )\n  .subscribe((status, err) => {\n    switch (status) {\n      case 'SUBSCRIBED':\n        console.log('Realtime connected')\n        break\n      case 'CHANNEL_ERROR':\n        console.error('Realtime error — is the table in the publication?', err)\n        \u002F\u002F Fix: ALTER PUBLICATION supabase_realtime ADD TABLE todos;\n        break\n      case 'TIMED_OUT':\n        console.error('Realtime timed out — check network')\n        break\n      case 'CLOSED':\n        console.log('Channel closed')\n        break\n    }\n  })\n\n\u002F\u002F Always clean up on unmount \u002F exit\nprocess.on('SIGINT', async () => {\n  await supabase.removeChannel(channel)\n  process.exit(0)\n})\n```\n\n### Example 4 — Connection pool exhaustion (PGRST000) in serverless\n\n```typescript\n\u002F\u002F BAD — creates a new client per request in serverless (Lambda, Edge Functions)\nexport async function handler(req: Request) {\n  const supabase = createClient(url, key)  \u002F\u002F new connection every invocation\n  const { data } = await supabase.from('todos').select('*')\n  return Response.json(data)\n}\n\n\u002F\u002F GOOD — reuse client across warm invocations\nconst supabase = createClient(url, key, {\n  auth: { autoRefreshToken: false, persistSession: false }\n})\n\nexport async function handler(req: Request) {\n  const { data, error } = await supabase.from('todos').select('*')\n  if (error) {\n    if (error.code === 'PGRST000') {\n      \u002F\u002F Pool exhausted — return 503 so the caller retries\n      return new Response('Service temporarily unavailable', { status: 503 })\n    }\n    return Response.json({ error: error.message }, { status: 400 })\n  }\n  return Response.json(data)\n}\n```\n\n## Resources\n\n- [Supabase JavaScript SDK Reference](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Freference\u002Fjavascript\u002Fintroduction)\n- [PostgREST Error Codes](https:\u002F\u002Fpostgrest.org\u002Fen\u002Fstable\u002Freferences\u002Ferrors.html)\n- [PostgreSQL Error Codes](https:\u002F\u002Fwww.postgresql.org\u002Fdocs\u002Fcurrent\u002Ferrcodes-appendix.html)\n- [Supabase Auth Error Handling](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Freference\u002Fjavascript\u002Fauth-error-codes)\n- [RLS Debugging Guide](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Fdatabase\u002Fpostgres\u002Frow-level-security)\n- [Supabase Realtime Troubleshooting](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Frealtime\u002Ftroubleshooting)\n- [Supabase Status Page](https:\u002F\u002Fstatus.supabase.com)\n\n## Next Steps\n\n- Use `supabase-debug-bundle` to generate a full diagnostic snapshot when errors persist after applying these fixes.\n- Use `supabase-security-basics` to audit your RLS policies and prevent `42501` errors proactively.\n- Use `supabase-known-pitfalls` for edge cases and SDK behavior that can cause subtle bugs.\n- Use `supabase-observability` to set up logging and alerting so you catch errors before users report them.\n",{"name":5,"tags":24,"author":32,"license":15,"version":33,"description":34,"allowed-tools":35,"compatible-with":36},[25,26,27,28,29,30,31],"saas","supabase","debugging","errors","postgrest","rls","auth","Jeremy Longshore \u003Cjeremy@intentsolutions.io>","1.0.0","Diagnose and fix Supabase errors across PostgREST, PostgreSQL, Auth, Storage, and Realtime.\nUse when encountering error codes like PGRST301, 42501, 23505, or auth failures.\nUse when debugging failed queries, RLS policy violations, or HTTP 4xx\u002F5xx responses.\nTrigger with \"supabase error\", \"fix supabase\", \"PGRST\", \"supabase 403\", \"RLS not working\",\n\"supabase auth error\", \"unique constraint\", \"foreign key violation\".\n","Read, Grep, Bash(curl:*), Bash(supabase:*), Bash(npx:*)","claude-code, codex, openclaw","main","99825ad3f3bcc6597ddcc7294a14e6e922f2b67b","skills\u002Fsaas-packs--supabase-pack--supabase-common-errors",0,"https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills","https:\u002F\u002Fgithub.com\u002Fjukeyman","https:\u002F\u002FRJBUSINESSSOLUTIONS.ORG","Credit and Finance Expert | Developer\r\n\r\nI'm Rick Jefferson, a seasoned credit and finance expert with over a decade of experience in financial literacy,","2026-07-13 07:03:29",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add jukeyman\u002Fjukeyman-skills --skill supabase-common-errors",{"tool":52,"command":53},"bunx","bunx skills add jukeyman\u002Fjukeyman-skills --skill supabase-common-errors",{"tool":55,"command":56},"pnpm","pnpm dlx skills add jukeyman\u002Fjukeyman-skills --skill supabase-common-errors","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--supabase-pack--supabase-common-errors\u002FSKILL.md",true,[],[61,68,75,82,89,97],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M79ANS2SM329NEP5ZCX106RR","zustand-store-creator","Create zustand store creator operations. Auto-activating skill for Frontend Development.\nTriggers on: zustand store creator, zustand store creator\nPart of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like \"zustand store creator\", \"zustand creator\", \"zustand\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzustand-store-creator\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M79AMZKP4YDEZ7EHG1Y7PP74","zero-trust-config-helper","Configure with zero trust config helper operations. Auto-activating skill for Security Advanced.\nTriggers on: zero trust config helper, zero trust config helper\nPart of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like \"zero trust config helper\", \"zero helper\", \"zero\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-config-helper\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M79AMJSBCEJQNBTYNAHYN5HM","zapier-integration-helper","Assist with zapier integration helper operations. Auto-activating skill for Business Automation.\nTriggers on: zapier integration helper, zapier integration helper\nPart of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like \"zapier integration helper\", \"zapier helper\", \"zapier\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzapier-integration-helper\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M79AHJZGVMARS13VFQYRR1MP","yaml-config-validator","Validate yaml config validator operations. Auto-activating skill for DevOps Basics.\nTriggers on: yaml config validator, yaml config validator\nPart of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like \"yaml config validator\", \"yaml validator\", \"yaml\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fyaml-config-validator\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":93,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M79AHGDZRN0020RDQSQDPAM8","xvary-stock-research","Thesis-driven equity analysis from public SEC EDGAR and market data; \u002Fanalyze, \u002Fscore, \u002Fcompare workflows with bundled Python tools (Claude Code, Cursor, Codex).","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M79AHCYJ9FV9RMHQ24HDRN33","xss-vulnerability-scanner","Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals.\nTriggers on: xss vulnerability scanner, xss vulnerability scanner\nPart of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like \"xss vulnerability scanner\", \"xss scanner\", \"xss\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxss-vulnerability-scanner\u002FSKILL.md",[],[]]