PostgreSQL cancels a statement that runs longer than the effective statement_timeout. The default setting is zero, which disables this server-side timeout, so a nonzero value may come from a role, database, session, or managed-provider configuration.
Why does this error happen?
- The query genuinely exceeded a configured duration.
- A role, database, or session override set a shorter value than expected.
- Lock waits consumed the statement's total elapsed time.
How do you diagnose it?
- Run SHOW statement_timeout in the same role and connection path as the failing request.
- Inspect pg_stat_activity and pg_locks while the query is active.
- Use EXPLAIN (ANALYZE, BUFFERS) only on safe representative queries and environments.
SHOW statement_timeout;
-- Scope a deliberate exception to the current transaction.
SET LOCAL statement_timeout = '30s';How do you fix it?
- Optimize the plan, indexes, or amount of work before raising the timeout.
- Set a deliberate session or transaction-local value for known long operations.
- Keep application/client timeouts coordinated so cancellation and retries do not create duplicate work.
How do you prevent it from recurring?
Turn the confirmed cause of SQLSTATE 57014 — query_canceled into an observable boundary for PostgreSQL. Track the relevant request count, token volume, payload size, execution time, connection pressure, billing state, or upstream health before it reaches the documented failure condition. Preserve the platform request ID and timestamp so future incidents can be correlated without logging sensitive payloads.
Test the fix under representative concurrency and failure injection, not only with one successful request. Alert on remaining headroom and repeated retries, and keep the linked limit page and official error source with the runbook so responders can distinguish a configuration problem from temporary service pressure or account state.