Skip to content
AnglinAI Docs

ERR_DB_QUERY_FAILED — Database Query Failed

HTTP Status: 500 Retryable: Yes Automatic retry: None at the general query level. Specific operations like credit deduction have their own retry logic for transient errors.

What the User Sees

A database operation failed. (ERR_DB_QUERY_FAILED)

What Causes This Error

A Supabase query or RPC function call failed after the connection was successfully established. Unlike connection errors (ERR_DB_CONNECTION_FAILED), this indicates the database is reachable but the specific operation could not be completed.

Common causes include: schema mismatch after a migration that did not run or partially ran, an RPC function that was dropped or modified, a database constraint violation (unique constraint, foreign key, check constraint), a query timeout on complex or long-running queries, or a permissions issue with the service role key.

This error may indicate a code/schema issue rather than an infrastructure problem, especially if it is reproducible. Transient versions of this error (timeouts, deadlocks) will self-resolve on retry, but persistent versions require investigation.

Resolution Steps

For Users

  1. Try the operation again. If it is a transient database issue, it may succeed on retry.
  2. If the error is persistent (same operation always fails), contact support with details about what you were doing when the error occurred.

For Administrators

  1. Check Supabase logs: Dashboard > Database > Logs. Look for the specific query that failed and the PostgreSQL error code.
  2. Review the API structured logs in Grafana for the full error context, including the query or RPC function name that failed.
  3. Common causes and fixes:
    • Missing migration: Run list_migrations to check if all migrations have been applied. Compare with the local migration files.
    • Missing RPC function: Check if the function exists: SELECT proname FROM pg_proc WHERE proname = 'function_name';
    • Missing column: A new column may not have been added. Check the table schema in Supabase dashboard.
    • Constraint violation: Check the error for constraint name and identify the conflicting data.
  4. If a migration needs to be applied, use the apply_migration Supabase MCP tool.
  5. For query timeouts, check the query execution plan and add appropriate indexes.