Supabase Troubleshooting

Supabase Troubleshooting

Guidance for debugging issues, viewing logs, running advisors, and searching documentation using MCP tools and CLI.

Viewing Logs (MCP)

The get_logs tool retrieves logs from the last 24 hours by service:

mcp__supabase__get_logs(project_id: "<id>", service: "<service>")

Available Services

Debugging Strategy

Start with the service most relevant to the issue:

1. API errors (4xx/5xx) → Check api logs for PostgREST errors
2. Query failures → Check postgres logs for SQL errors
3. Function crashes → Check edge-function logs for runtime errors
4. Login failures → Check auth logs for provider/token issues
5. File access denied → Check storage logs for policy violations
6. Connection drops → Check realtime logs for WebSocket issues

Security Advisors (MCP)

mcp__supabase__get_advisors(project_id: "<id>", type: "security")

The advisor runs Supabase's Splinter lint catalog against the live database. Common security lint codes you'll see:

The advisor also surfaces performance lints (e.g. 0001 unindexed_foreign_keys, 0003 auth_rls_initplan, 0006 multiple_permissive_policies) when called with type: "performance".

Include remediation URLs as clickable links in responses — each lint has a dedicated docs page at https://supabase.github.io/splinter/<code>_<name>/.

Static counterpart: for the lints that can be detected without a live database (0002, 0003, 0008, 0011, 0013, 0015), run python scripts/audit-rls.py against your migration files. Useful in CI before push.

Performance Advisors (MCP)

mcp__supabase__get_advisors(project_id: "<id>", type: "performance")

Returns performance advisory notices:

• Missing indexes on frequently queried columns
• Bloated tables needing VACUUM
• Unused indexes consuming space
• Slow query patterns

Run after DDL changes to catch performance regressions early.

Searching Documentation (MCP)

The search_docs tool queries Supabase's documentation via GraphQL:

mcp__supabase__search_docs(
  graphql_query: "{ searchDocs(query: \"<search terms>\", limit: 5) { nodes { title href content } } }"
)

Effective Search Queries

Advanced GraphQL Queries

Search with subsections for deeper results:

{
  searchDocs(query: "connection pooling", limit: 3) {
    nodes {
      title
      href
      content
      ... on Guide {
        subsections {
          nodes {
            title
            content
          }
        }
      }
    }
  }
}

Search for CLI command references:

{
  searchDocs(query: "supabase db push", limit: 3) {
    nodes {
      title
      href
      ... on CLICommandReference {
        content
      }
    }
  }
}

Look up specific error codes:

{
  error(code: "user_already_exists", service: AUTH) {
    code
    service
    httpStatusCode
    message
  }
}

CLI Diagnostic Tools

Database Linting

supabase db lint

Checks the schema for common issues: missing primary keys, unindexed foreign keys, naming inconsistencies.

Database Inspection

supabase inspect db calls           # Most frequently called queries
supabase inspect db long-running    # Long-running queries
supabase inspect db outliers        # Queries with worst time/calls ratio
supabase inspect db bloat           # Table bloat estimates
supabase inspect db cache-hit       # Buffer cache hit ratios
supabase inspect db index-usage     # Index utilization
supabase inspect db locks           # Current lock contention
supabase inspect db replication-slots  # Replication slot status
supabase inspect db role-connections   # Connection counts per role
supabase inspect db seq-scans       # Tables with high sequential scans
supabase inspect db table-sizes     # Table size breakdown
supabase inspect db unused-indexes  # Indexes that are never used
supabase inspect db vacuum-stats    # Last vacuum/analyze timestamps

Local Stack Diagnostics

supabase status     # Show all local service URLs and health
supabase stop       # Stop and optionally reset local stack
supabase start      # Restart local stack

Common Issues and Solutions

"Permission Denied" on Table Access

Cause: RLS is enabled but no policy grants access for the user's role.

Diagnosis:

1. Check RLS status: SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname = 'public';
2. Check policies: SELECT * FROM pg_policies WHERE tablename = '<table>';
3. Run security advisor: get_advisors(type: "security")

Fix: Create appropriate RLS policies for the table.

Edge Function Returns 500

Diagnosis:

1. Check function logs: get_logs(service: "edge-function")
2. Check if secrets are set: supabase secrets list
3. Test locally: supabase functions serve

Common causes:

• Missing environment variable / secret
• Unhandled exception in function code
• Incorrect import path or missing dependency
• JWT verification failure (check verify_jwt setting)

Slow Queries

Diagnosis:

1. Run performance advisor: get_advisors(type: "performance")
2. Check for missing indexes
3. Use EXPLAIN ANALYZE via execute_sql

EXPLAIN ANALYZE SELECT * FROM public.posts WHERE author_id = '<uuid>';

Fix: Add indexes on columns used in WHERE clauses, JOINs, and RLS policies.

Auth Provider Not Working

Diagnosis:

1. Check auth logs: get_logs(service: "auth")
2. Verify provider configuration in Dashboard
3. Check redirect URLs match exactly

Common causes:

• Mismatched redirect URLs
• Invalid client ID/secret
• Missing scopes for the provider

Realtime Not Receiving Updates

Diagnosis:

1. Check realtime logs: get_logs(service: "realtime")
2. Verify RLS policies allow the subscription
3. Verify the table has REPLICA IDENTITY FULL if needed

ALTER TABLE public.messages REPLICA IDENTITY FULL;

Migration Push Fails

Diagnosis:

1. List applied migrations: list_migrations
2. Check for conflicts with supabase db diff
3. Verify migration SQL is valid

Common causes:

• Migration already applied (different hash)
• Dependency ordering issue
• Syntax error in SQL

Fix: Use supabase migration repair to fix migration history, or write a corrective migration.

Diagnostic Workflow

For any Supabase issue, follow this sequence:

1. Identify the service — Which Supabase component is involved?
2. Check logs — get_logs for the relevant service
3. Run advisors — get_advisors for security and performance
4. Search docs — search_docs for the specific error or pattern
5. Test locally — Reproduce the issue with supabase start if possible
6. Inspect database — Use supabase inspect db commands for deep analysis