obsidian/wiki/tech-patterns/payload-cms-locked-documents.md

title	aliases	tags	sources	created	updated
Payload CMS — Document Locking	payload-lock payload-document-locking payload-concurrency	payload-cms concurrency admin-panel collaboration	raw/admin__locked-documents.md	2026-05-15	2026-05-15

Payload CMS — Document Locking

Prevents concurrent edits to the same document by locking it to the first editor. Affects Admin Panel, REST API, and Local API.

How It Works

1. User opens a document for editing → Payload locks it to that user.
2. Second user hitting the same document sees a prompt with three options:
   • View in Read-Only — no changes allowed.
   • Take Over — steals the lock; original editor is notified.
   • Return to Dashboard — navigate away.
3. Lock auto-expires after inactivity (duration seconds, default 300).

Configuration

Enabled by default on all collections and globals. Configure via lockDocuments on the collection/global config:

import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  lockDocuments: {
    duration: 600, // seconds; default is 300
  },
}

To disable locking entirely:

lockDocuments: false

Options Reference

Option	Type	Default	Description
lockDocuments	object | false	enabled	Enable/disable locking. Pass object to configure.
duration	number	300	Inactivity timeout in seconds before lock expires.

API Behaviour

• REST & Local API: a locked document blocks update and delete for other users.
• Default overrideLock: true — locks are ignored by API calls unless explicitly set to false.

Enforcing Locks via API

const result = await payload.update({
  collection: 'posts',
  id: '123',
  data: { title: 'New title' },
  overrideLock: false, // respect the lock — error if locked by another user
})

Use overrideLock: false in workflows where you want strict concurrency control. Use the default (true) for admin/background operations that should bypass locks.

Key Takeaways

• Document locking is on by default — no setup required for basic concurrency protection.
• Lock duration defaults to 5 minutes (300s); tune duration for your editing cadence.
• The Admin Panel UI handles the UX (take-over / read-only prompts) automatically.
• REST and Local API calls ignore locks by default (overrideLock: true) — set overrideLock: false to enforce them.
• Disable per-collection with lockDocuments: false when locking adds friction without benefit (e.g. single-editor configs).

Related

• wiki/tech-patterns/payload-cms-collection-access-control — unlock operation on access control
• wiki/tech-patterns/payload-cms-access-control-overview
• wiki/tech-patterns/payload-cms-installation
• wiki/tech-patterns/payload-cms-globals-access-control

Sources

• raw/admin__locked-documents.md — from https://payloadcms.com/docs/admin/locked-documents