log_lock_failures

Definition PG 18 manual

Controls whether a detailed log message is produced when a lock acquisition fails. This is useful for analyzing the causes of lock failures. Currently, only lock failures due to SELECT NOWAIT is supported. The default is off. Only superusers and users with the appropriate SET privilege can change this setting.

How it works

log_lock_failures was introduced in PostgreSQL 18 to emit a detailed message when a supported lock acquisition fails. In PostgreSQL 18 the supported scope is specifically lock failure caused by SELECT ... NOWAIT; it is not a general logger for every NOWAIT-like command or every lock error.

It is a SUPERUSER-context setting. A superuser or a role with the appropriate SET privilege can change it per session, so role/database defaults and connection-pool reset behavior determine which sessions produce records.

It complements log_lock_waits: log_lock_waits reports waits that cross deadlock_timeout, whereas SELECT ... NOWAIT fails immediately and can be reported here. The detailed message can expose relation, lock, and statement context and must follow the normal log access policy.

Operational considerations

Assuming PostgreSQL 18 logs every lock acquisition failure; currently only SELECT ... NOWAIT is supported.

Using it instead of log_lock_waits even though immediate failure and a wait exceeding deadlock_timeout are different events.

Enabling it in one pooled session and assuming other sessions inherited the value.

Retaining detailed lock and statement context without appropriate log access, redaction, and retention controls.

Workload guidance

OLAP: Analytical readers using SELECT ... NOWAIT can use it during contention investigations; leave it off if those commands are absent because it supplies no broader wait telemetry.

OLTP: Enable it for sessions where SELECT ... NOWAIT failure explains latency or retry behavior, and correlate records with application retries and lock holders. Do not expect coverage of unrelated lock errors.

SMALL: The normal volume is low, but verify log access and retention before enabling. Pair it with log_lock_waits and deadlock diagnostics rather than treating it as a replacement.