A deadline for acquiring a lock
PostgreSQL lock_timeout limits time spent waiting to acquire a lock. It has a different scope from statement_timeout, which limits a statement’s overall execution time. A lock-timeout error does not by itself prove corruption or a deadlock cycle. It tells you that a required resource did not become available within the chosen budget. Long transactions, conflicting DDL and concentrated updates to a hot row are different possible causes. Diagnose the dependency before treating every timeout as evidence that the database needs a larger global limit.
Two updates meet on one row
Suppose session A begins a transaction, updates an account row and then remains open without committing. Session B tries to update the same row and may have to wait for A’s transaction outcome. In a controlled experiment, B can use SET LOCAL lock_timeout = '2s' inside its own transaction to demonstrate the error. Two seconds is an example, not a recommended production setting. Failing faster reduces one waiting period but does not release A’s lock or guarantee that a subsequent retry can complete useful work.
BEGIN;
SET LOCAL lock_timeout = '2s';
-- Controlled test only: may wait for another transaction.
UPDATE accounts SET balance = balance + 1 WHERE id = 1;
ROLLBACK;Identify the actual blocker
Inspect session state and wait events through pg_stat_activity and use pg_blocking_pids to identify blockers. pg_locks provides further lock information, but row-lock waits are not necessarily represented as a simple complete list of locked rows. Connect the blocker to its transaction start time, current activity and owner. An idle-in-transaction session can hold resources despite not actively executing a statement. Killing the oldest PID without understanding its business operation can cause a costly rollback or interrupt important work, so termination is an operational decision rather than a mechanical first step.
Handle the failed transaction deliberately
After an error, the transaction’s failed state must be handled before normal work can continue. The application usually rolls back the whole transaction or returns to a deliberately established savepoint. If retrying, define the retry boundary and idempotency assumptions, and impose a finite budget with a delay. Consistent lock acquisition order and avoiding external I/O inside a transaction can reduce blocking at its source. Merely increasing a timeout leaves the dependency and occupied connection in place; evaluate both the user-visible failure policy and the underlying contention.