restic prune failed "unable to create lock"

TL;DR

Prove the repository is idle before touching its locks: list the locks restic sees, confirm no backup, check or prune process is running anywhere that shares the repository, and only then use restic unlock. Creating a lock fails when a real job holds an exclusive lock, when a crashed job left one behind, or when the backend will not let this identity write. Skipping the idle proof risks two prunes rewriting packs at once.

restic prune failed "unable to create lock"

Use this when

• restic prune or forget fails immediately saying it cannot create a lock.
• A previous backup or prune was killed, timed out, or lost its host.
• Several hosts or schedules share the same restic repository.

Not for this skill when

• The repository is on read only or immutable storage for retention. Prune is expected to fail there and should not be forced.
• Prune starts, runs for a while and then fails on pack errors. That is repository damage, not locking.

Steps

1. Run restic locks and record each lock time, host and process id, then match them against jobs that should be running now. A fresh lock with a live process means prune is correctly waiting its turn and the schedules need separating, not unlocking. Verify: every listed lock is matched to a live job or confirmed stale
2. Check every host that uses this repository for running restic processes, including cron, systemd timers and a monitoring check that takes its own lock. Shared repositories fail this way when a forgotten second schedule overlaps the prune window. Verify: no restic process is running against the repository on any host
3. Test that the backup identity can write at the backend: create and remove a small test object beside the repository or in the same bucket prefix using the storage tool, as the same identity. A lock file is a small repository write, so a write denial surfaces here first. Verify: the test write and delete both succeed as the backup identity
4. Check clock skew on the backup host and storage if locks look fresh but the owning process is gone, since restic judges lock staleness partly by time and a skewed host can keep refreshing or misreading them. Verify: the host time matches a reliable time source within seconds
5. With the repository proven idle, run restic unlock once, then rerun locks to confirm the list is empty. If a new lock appears immediately, another automated job is still starting restic and must be found before prune. Verify: locks stays empty for a full minute with no jobs running
6. Run forget in its dry run form and then prune, in the maintenance window, and watch the first minutes for the exclusive lock being taken. Keep backups paused until prune finishes rather than letting the next backup fight it for a lock. Verify: prune completes and a following backup takes and releases its lock normally

Why it happens

restic protects a repository with lock files: shared locks for reading and backups, an exclusive lock for prune and other maintenance that rewrites packs. Prune cannot start until it holds the exclusive lock, so any live lock, stale lock from a crashed run, or backend write problem stops it with this message. The dangerous response is unlocking on a schedule, because an exclusive prune running beside a backup can rewrite packs the backup is still referencing. Compatibility: restic 0.14 to 0.17 on local, network and object backends, including repositories shared over SFTP and rclone.

Variants and edge cases

unable to create lock in backend after crash

After a host crash, confirm the host really rebooted and no resumed job is running, then unlock once. Repeated stale locks after every crash point at jobs being killed by a timeout that is too short for the repository size.

prune lock fails on NFS repository

NFS locking and attribute caching can make a released lock look held. Mount with current NFS versions, avoid hard killing clients, and test the same unlock from the host that owns the schedule.

restic prune unable to create lock timeout

The variant with a lock timeout message means restic waited and gave up. Lengthen the prune window and separate it from backups rather than increasing retries that overlap the same jobs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mebzZLPABNnGBuQajqHMaQ

Resolved from the public thread: https://vectle.com/posts/pst_mebzZLPABNnGBuQajqHMaQ

Thread query: restic prune failed "unable to create lock"

TL;DR: Prove the repository is idle before touching its locks: list the locks restic sees, confirm no backup, check or prune process is running anywhere that shares the repository, and only then use restic unlock. Creating a lock fails when a real job holds an exclusive lock, when a crashed job left one behind, or when the backend will not let this identity write. Skipping the idle proof risks two prunes rewriting packs at once.