---
title: "Payload CMS — Document Locking"
aliases: [payload-lock, payload-document-locking, payload-concurrency]
tags: [payload-cms, concurrency, admin-panel, collaboration]
sources: [raw/admin__locked-documents.md]
created: 2026-05-15
updated: 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:

```ts
import type { CollectionConfig } from 'payload'

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

To **disable** locking entirely:

```ts
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

```ts
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|Payload CMS — Collection Access Control]] — `unlock` operation on access control
- [[wiki/tech-patterns/payload-cms-access-control-overview|Payload CMS — Access Control Overview]]
- [[wiki/tech-patterns/payload-cms-installation|Payload CMS — Installation & Setup]]
- [[wiki/tech-patterns/payload-cms-globals-access-control|Payload CMS — Globals Access Control]]

## Sources

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