About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
The message means another restic process has a lock file in the repository that conflicts with the one you asked for. Either that process is still running (a long backup, a prune, a check, or an overlapping schedule), or it was killed and left its lock behind. The fix depends on which, and restic unlock is only the right answer for the second case.
Do not start with unlock --remove-all. Start by reading the lock: it records the host, user, process ID and creation time of whoever holds it.
What the error means
restic coordinates processes that share a repository with small lock files. According to the restic design reference, each lock is a file in the repository's locks directory holding a JSON document with the fields time, exclusive, hostname, username, pid, uid and gid.
There are two kinds. "Locks come in two types: Exclusive and non-exclusive locks." At most one process may hold an exclusive lock, and no other lock may exist while it does; any number of non-exclusive locks can coexist.
In the restic source (v0.19.1, internal/restic/lock.go), the message is built as repository is already locked <exclusively >by <lock>, and the lock prints itself as three lines: process ID, host and user with UID and GID; the creation time and age; and a storage ID. The caller wraps it as unable to create lock in backend: .... This layout comes from the source code, not from a captured run, so treat the exact wording on your version as something to read rather than assume.
Which commands take which lock matters. In the v0.19.1 source, backup and key add take a non-exclusive lock, restore takes a read lock (in the source a read lock is also non-exclusive, not a third kind), while check, forget, prune, tag and repair snapshots take an exclusive one. The documentation says only that "during a prune operation, the repository is locked and backups cannot be completed" (forget and prune), and that a client removing data "must acquire an exclusive lock first". Together these explain a common overlap: a 02:00 backup still running when a 02:15 forget --prune starts, or the reverse.
When restic itself calls a lock stale
The design reference says a lock is stale when its timestamp is older than 30 minutes. For a lock created on the same machine, restic also signals the owning process; if the process is gone, the lock is stale even if it is younger than 30 minutes. A lock from a different host is never judged by process, only by age. The source shows a running restic refreshing its lock every 5 minutes (defaultRefreshInterval), which is why a healthy long job does not go stale.
The exit status is useful in scripts: "Failed to lock repository (since restic 0.17.0)" is exit code 11 (scripting).
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| Another job is genuinely running | Lock created minutes ago on a known host; process ID exists there | restic cat lock <lock-ID> --no-lock shows host and PID; check that process on that host |
| Overlap between backup and prune/check | Lock marked exclusive, or your command is the exclusive one | Compare the schedules; the holder's exclusive field is true |
| Job killed or host rebooted | Lock older than 30 minutes, or PID gone on the same host | Lock time; process list on the named host |
| Lock from another host that died | Hostname differs from the machine you are on | Only the 30-minute age rule applies to it |
| Unreadable or corrupt lock file | restic reports an invalid lock and suggests unlock --remove-all |
The error text itself; empty lock files left by failed uploads have been ignored since 0.15.1 (changelog) |
| Repeated stale locks on odd storage | New stale locks after every interrupted run | Known fixes: SIGTERM handling (0.17.0), chmod failure on CIFS or WebDAV-mounted storage (fixed 0.19.0) |
Prove the cause before changing anything
These commands are taken from the restic documentation and source and have not been run.
restic list locks
restic cat lock <lock-ID> --no-lock
list accepts locks as an object type, and cat accepts lock ID. The cat output is the JSON document described above.
Only list locks is read-only without extra help. In the v0.19.1 source, restic cat lock takes a non-exclusive lock of its own unless you add --no-lock ("do not lock the repository"). Without it, cat lock writes a lock file to the repository and fails with the same "already locked" error while an exclusive prune or check holds the lock, which is exactly the case you are trying to inspect. With --no-lock it writes nothing. Read:
exclusive: is the holder a prune/check/forget, or a backup?hostnameandpid: go to that host and see whether the process exists. On the same host restic does this check itself.time: the creation time. Because a live restic refreshes its lock, a time more than 30 minutes old means no live process is refreshing it.
If the repository is on object storage, remember that the host named in the lock may be a different machine from the one you are on. Never decide on the basis of the machine you are standing at.
Example (illustrative): a nightly backup on APP01 fails with the already-locked message. restic list locks shows one lock. restic cat lock <lock-ID> --no-lock shows "hostname": "BACKUP01", "exclusive": true, "pid": 48211, "time" 14 minutes ago. BACKUP01 has a restic forget --prune still running from the previous cycle. The lock is live, not stale. Unlocking would be wrong; the correct response is to stop the two schedules overlapping.
Fix
Cause 1 and 2: a live job, or overlapping jobs
Wait for the holder to finish. To let a job wait rather than fail, restic has a global --retry-lock option: "retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries)". It was added in 0.16.0.
The lasting fix is scheduling. The restic backup documentation says: "When scheduling restic to run recurringly, please make sure to detect already running instances before starting the backup" (backing up). Run prune and check in a window when no backup runs, because their exclusive lock excludes every other lock.
Cause 3 and 4: a dead holder
Confirm first that the holder is dead (the checks above), then:
restic unlock
The unlock manual page says it "removes stale locks that have been created by other restic processes." It does not touch live locks. If the lock is from another host and younger than 30 minutes, restic will not call it stale; wait until it passes 30 minutes rather than forcing it.
Cause 5: an invalid lock
The source prints this guidance with the invalid-lock error: the unlock --remove-all command "can be used to remove invalid locks. Make sure that no other restic process is accessing the repository when running the command."
Risky step. restic unlock --remove-all is documented as "remove all locks, even non-stale ones". The design reference says a client removing data must hold an exclusive lock first, so removing a live backup's lock could let a prune run beside that backup and remove data it is still writing. Treat that as the risk. Confirm with restic list locks and the process lists on every host that uses the repository, and stop schedules first.
Cause 6: recurring stale locks
Match the symptom to the changelog: killed processes (0.17.0 made restic shut down cleanly on SIGTERM), Fatal: failed to refresh lock in time on slow links or after standby (0.16.0), and chmod ...: operation not supported when removing stale locks on CIFS or WebDAV-mounted storage (introduced 0.18.0, fixed 0.19.0). If you are on an affected version, upgrade rather than unlock repeatedly. Test the upgrade on a non-production repository first.
Confirm the fix
restic list locksshows no locks while all jobs are idle, and only the expected ones while a job runs.- The next scheduled run finishes with exit code 0, not 11.
- A lock-free result is not a restore. The documentation notes that
check"does not verify that the actual pack files on disk in the repository are unmodified" unless you add--read-dataor--read-data-subset=n/t(working with repositories). Run acheckin a quiet window, then restore a sample to a scratch directory withrestic restore latest --target <directory>(the manual: "The special snapshotID "latest" can be used to restore the latest snapshot", restore). Compare what you restored with the source.
What to watch afterwards
- Alert on exit code 11 separately from other failures. In the scripting reference, an unknown exit code "MUST be treated as a command failure", so never treat 11 as success.
- Alert on a lock whose age is over 30 minutes while no job is scheduled.
- Keep a written timetable of backup, forget/prune and check windows per repository. Two repositories on the same schedule is fine; two jobs on one repository is where this error starts.
- If several hosts back up into one repository, the 30-minute rule is the only automatic defence against a dead remote holder.
Read next
Related articles you may want next.
- Backup & RecoveryWhat restic and Borg repository checks prove, and what only a restore canWhat restic check, --read-data, borg check and --verify-data actually prove, what they cost, and the restore test that covers what they cannot.Read article
- Backup & RecoveryImmutable Backup Repositories on Linux: Hardened Design, Attributes, Credentials and LimitsWhat the Linux immutable attribute enforces, who can still remove it, and how to design credentials, retention and clocks so backups cannot be erased.Read article
- Backup & RecoveryBorg warnings 'cache is newer than repository' and 'repository was previously located at': what each meansBorg warns the cache is newer than the repository, or that it was previously located elsewhere. What each check means and what is safe to do.Read article
Risks and limits
- These commands have not been run or lab-tested. They are taken from the restic documentation and source.
- The documentation pages show no date; the manual page names itself "restic 0.19.1 documentation". Lock behaviour was read from the source tags v0.17.3, v0.18.1 and v0.19.1, which agree on the 30-minute stale rule, the 5-minute refresh and the already-locked wording. The 0.16.x series differs in refresh handling (changelog entries #4199 and #4274).
- The exact printed layout of the message is derived from source code, not from a recorded run.
- Which command takes which lock is read from v0.19.1 and may change between versions.
- The
restic unlockmanual states what it removes but not how it judges staleness; that comes from the design reference and source. - Repositories on remote services may add their own locking or immutability rules that are outside restic's documentation.
Sources
- Design: locks — restic project documentation, date not shown, accessed 16 November 2026
- Scripting and exit codes — restic project documentation, date not shown, accessed 16 November 2026
- Removing backup snapshots (forget and prune) — restic project documentation, date not shown, accessed 16 November 2026
- Backing up — restic project documentation, date not shown, accessed 16 November 2026
- Working with repositories — restic project documentation, date not shown, accessed 16 November 2026
- Manual (global flags) — restic project documentation, date not shown, accessed 16 November 2026
- restic-unlock(1) — restic project (GitHub), date not shown, accessed 16 November 2026
- restic-cat(1) — restic project (GitHub), date not shown, accessed 16 November 2026
- restic-list(1) — restic project (GitHub), date not shown, accessed 16 November 2026
- restic-restore(1), v0.19.1 — restic project (GitHub), date not shown, accessed 16 November 2026
- restic source, internal/restic/lock.go and internal/repository/lock.go, v0.19.1 — restic project (GitHub), release dated 2026-07-05 per the changelog, accessed 16 November 2026
- restic source, cmd/restic (lock choice per command), v0.19.1 — restic project (GitHub), accessed 16 November 2026
- restic CHANGELOG — restic project (GitHub), latest entry 0.19.1 (2026-07-05), accessed 16 November 2026
This article was originally published on .