55P03

At a glance

55P03 reports that a requested lock could not be obtained under the operation's selected wait policy. Fixed paths cover row locks, relation locks, LOCK TABLE, lock_timeout, and maintenance commands that skip work.

Meaning

Row-lock callers use LockWaitError and ConditionalXactLockTableWait()/ConditionalMultiXactIdWait() to fail immediately with could not obtain lock on row in relation "%s". Relation and LOCK TABLE callers use ConditionalLockRelationOid() and report a relation variant. A lock_timeout interrupt is another ERROR path, canceling statement due to lock timeout; it means the wait exceeded the configured timeout, not that NOWAIT was requested.

VACUUM and ANALYZE use the same SQLSTATE when they cannot acquire their relation lock, but their ereport(elevel) is deliberately non-ERROR: ordinary maintenance reports a WARNING, and an autovacuum verbose path can use LOG. The command skips that object and continues, so a warning is not an aborted transaction.

Diagnosis

Keep the complete primary message, severity, relation or row name, lock mode, and statement. Inspect pg_stat_activity, pg_locks, blocker PIDs, transaction age, and whether the statement used NOWAIT, lock_timeout, or a maintenance command. Do not turn a skipped VACUUM/ANALYZE warning into a failed DML diagnosis.

The accepted row-lock case used a separate blocker and an autocommit contender. In an explicit transaction, a lock ERROR leaves the session INERROR until ROLLBACK or ROLLBACK TO SAVEPOINT; the accepted autocommit contender remained IDLE after its failed statement.

Response

Coordinate or release the blocker, or choose a deliberate wait/timeout/skip policy. For an ERROR in an explicit transaction, roll back the whole transaction or to an existing savepoint before issuing more SQL; verify which work was committed before replaying. In autocommit, change the blocking or timeout condition first, then retry the statement with an idempotency rule. For a maintenance WARNING/LOG, record the skipped relation and run maintenance later; do not issue ROLLBACK for a command that did not abort the transaction.

Observed diagnostics

The selected registry created a blocker holding SELECT ... FOR UPDATE in an explicit transaction and an autocommit contender issuing FOR UPDATE NOWAIT. PostgreSQL 18.6 and 10.21 returned ERROR / 55P03 with could not obtain lock on row in relation "nowait_rows"; the contender stayed IDLE. After the blocker rolled back, the same contender updated marker to repaired and verified it.

Representative case

The SQL is a role-labelled registry excerpt. Setup is run once; blocker and contender must be separate sessions. It covers the row-lock NOWAIT branch only, not lock_timeout or the maintenance skip branches.

-- setup (one maintenance session)
CREATE TABLE nowait_rows(id integer PRIMARY KEY, marker text NOT NULL);
INSERT INTO nowait_rows VALUES (1, 'seed');

-- blocker session: keep this transaction open
BEGIN;
SELECT id FROM nowait_rows WHERE id = 1 FOR UPDATE;

-- contender session, autocommit on: this is the 55P03 operation
SELECT id FROM nowait_rows WHERE id = 1 FOR UPDATE NOWAIT;

-- blocker session
ROLLBACK;

-- contender session after the blocker is released
UPDATE nowait_rows SET marker = 'repaired' WHERE id = 1 RETURNING marker;
SELECT marker FROM nowait_rows WHERE id = 1;

The passed case confirms this row-lock mechanism, its ERROR/IDLE boundary, and its repair step only; it does not prove that every lock mode or maintenance command has the same severity.

Versions

The locked catalogue records this condition from 8.0.0; fixed source coverage is PostgreSQL 18.6. The accepted runtime was observed on PostgreSQL 18.6 and 10.21.

Related

55P02, 40001, 57014

Sources

src/backend/access/heap/heapam.c#L5178-5210

src/backend/catalog/namespace.c#L585-610

src/backend/tcop/postgres.c#L3420-3444

src/backend/commands/lockcmds.c#L130-145

src/backend/commands/vacuum.c#L835-880

The structured evidence record records fixed message roles, maintenance severity, and accepted runtime artifacts.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/access/heap/heapam.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/catalog/namespace.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/tcop/postgres.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/commands/lockcmds.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/commands/vacuum.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• verify/cases/55P03/cases.json · ·
• verify/cases/55P03/snippets.json · ·
• verify/results/ops-55p03-latest-1/latest/summary.json · ·
• verify/results/ops-55p03-latest-1/latest/raw.jsonl · ·
• verify/results/ops-55p03-pg10-1/pg10/summary.json · ·
• verify/results/ops-55p03-pg10-1/pg10/raw.jsonl · ·

Message templates

could not obtain lock on row in relation "%s"

could not obtain lock on relation "%s.%s"

canceling statement due to lock timeout

could not obtain lock on relation "%s"

skipping vacuum of "%s" --- lock not available

skipping analyze of "%s" --- lock not available

Reproduction & repair cases

Recorded runtime evidence

{
  "table": "\"c55p03_nowait_row_lock\".\"nowait_rows\"",
  "statuses": {
    "blocker_after_lock": "INTRANS",
    "blocker_after_release": "IDLE",
    "contender_after_nowait": "IDLE",
    "contender_after_repair": "IDLE"
  },
  "diagnostic": {
    "text": "could not obtain lock on row in relation \"nowait_rows\"",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "55P03",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "heapam.c",
    "source_line": "5235",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "LockNotAvailable",
    "internal_query": null,
    "message_detail": null,
    "constraint_name": null,
    "message_primary": "could not obtain lock on row in relation \"nowait_rows\"",
    "source_function": "heap_lock_tuple",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "repair_marker": "repaired",
  "synchronization": "The blocker acquired SELECT FOR UPDATE before the contender issued SELECT FOR UPDATE NOWAIT; no timing sleep is used.",
  "connections_autocommit": {
    "blocker": true,
    "contender": true
  }
}

{
  "table": "\"c55p03_nowait_row_lock\".\"nowait_rows\"",
  "statuses": {
    "blocker_after_lock": "INTRANS",
    "blocker_after_release": "IDLE",
    "contender_after_nowait": "IDLE",
    "contender_after_repair": "IDLE"
  },
  "diagnostic": {
    "text": "could not obtain lock on row in relation \"nowait_rows\"",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "55P03",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "heapam.c",
    "source_line": "5074",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "LockNotAvailable",
    "internal_query": null,
    "message_detail": null,
    "constraint_name": null,
    "message_primary": "could not obtain lock on row in relation \"nowait_rows\"",
    "source_function": "heap_lock_tuple",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "repair_marker": "repaired",
  "synchronization": "The blocker acquired SELECT FOR UPDATE before the contender issued SELECT FOR UPDATE NOWAIT; no timing sleep is used.",
  "connections_autocommit": {
    "blocker": true,
    "contender": true
  }
}