restic / Troubleshooting
restic Reports the Repository Is Already Locked
Capture the restic exit code, separate a still-running lock from a stale one, then use the documented unlock command without disabling locking for write operations.
restic is a backup program that saves multiple revisions of files and directories in an encrypted repository stored on different backends. The restic References design documentation states that the repository structure allows parallel access by multiple restic instances and even parallel writes. Locks are exclusive or non-exclusive: at most one exclusive lock may exist, no other lock may exist while an exclusive lock exists, and multiple non-exclusive locks may coexist. Only a conflicting lock prevents another operation.[2]
The restic stable manual documents exit status 11 as the response when a restic command needs a lock and the repository is already locked. Exit status 10 means the repository does not exist, and exit status 12 means the password is incorrect; these are different observations and need their own diagnosis.[1]
Applicability
- Products
- restic
- Scope
- For a Linux or other supported host running the restic backup program against a supported repository backend, where the restic command reports that the repository is already locked. The current stable release at the time of writing is restic 0.19.1, released on 2026-07-05. This page does not cover a repository that does not exist (exit 10) or a wrong password (exit 12), which need their own diagnosis.[1][3]
- Last verified
Symptoms
- A restic command fails because the lock it needs conflicts with an existing repository lock, and the restic output and exit code report that the repository is already locked (documented exit status 11). This does not mean that all overlapping restic operations are forbidden: the restic References design documentation allows parallel instances and parallel writes, with exclusive and non-exclusive locks, and only conflicting locks prevent another operation. An old dashboard message, a different exit code, a connection error to the backend, or a wrong-password response is a different observation.[1][2]
Quick diagnosis
Read the exit code and the exact error before choosing a branch. A concurrent or stale lock is a different observation from a missing repository or a wrong password.
Record the exact exit code and message
Re-run the failing restic command and capture the complete output and the process exit code. The restic stable manual documents exit status 11 for an already-locked repository; exit 10 means the repository does not exist, exit 12 means the password is incorrect, exit 1 is a fatal error without a snapshot created, and exit 3 means some source data could not be read.[1]
Identify the restic command, repository, and host
Record the exact restic subcommand (for example backup, check, prune, forget, snapshots, unlock), the repository location (local path or backend URL, with any environment variable or repository file used), and every host that targets the same repository. The References design documentation allows parallel restic instances and even parallel writes, so overlapping jobs are not automatically forbidden; the task is to identify the conflicting lock, including one held by another host. The restic stable manual describes subcommands and flags separately; do not assume a flag that is not documented.[1][2]
Inspect the conflicting lock metadata
Enumerate repository locks with restic list locks, then inspect the suspected lock with restic cat lock <lock-id>. The lock object records the time, exclusive state, hostname, username, PID, uid, and gid. Use the exclusive field to determine whether the lock conflicts with the failing command, and use hostname, PID, and timestamp to determine whether the holder may still own it. The References design documentation allows multiple non-exclusive locks in parallel; do not treat the mere presence of another lock as proof of a conflict.[2]
restic list locksrestic cat lock <lock-id>Keep the repository and schedule configuration untouched
Do not delete or move the repository, remove the local cache, change the password, or rewrite scheduled jobs while diagnosing. Do not serialize all restic jobs unnecessarily: the References design documentation allows parallel restic instances and even parallel writes, with multiple non-exclusive locks permitted in parallel. Changing other components during the diagnosis can make a stale lock appear active or an active conflicting lock appear stale.[1][2]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Safe diagnostic guidanceIs this a restic command reporting a locked repository?
Confirm the command is restic, the target is a restic repository, and the current response is about locking rather than a different restic error.[1]
Read the complete diagnostic tree without using the controls
- Is this a restic command reporting a locked repository?
Confirm the command is restic, the target is a restic repository, and the current response is about locking rather than a different restic error.[1]
- Yes, a restic lock error → What is the current restic exit code and message?
- No, or applicability is unknown → Investigate the actual restic error or repository state
- What is the current restic exit code and message?
Use the captured exit code and message. The restic stable manual documents exit 11 for an already-locked repository, exit 10 for a non-existent repository, and exit 12 for an incorrect password.[1]
- Exit 11: repository is already locked → Have you identified the conflicting lock and inspected its hostname, PID, exclusive state, and time?
- Exit 10: repository does not exist → Investigate the actual restic error or repository state
- Exit 12: password is incorrect → Investigate the actual restic error or repository state
- Different error or backend failure → Investigate the actual restic error or repository state
- Have you identified the conflicting lock and inspected its hostname, PID, exclusive state, and time?
Use restic list locks to enumerate repository locks, then use restic cat lock <lock-id> to inspect the suspected conflicting lock. Record the hostname, PID, exclusive state, and time. The restic References design documentation allows parallel access and multiple non-exclusive locks, so only proceed after identifying the conflicting lock. A lock recorded on another hostname cannot be cleared as stale from local process evidence alone.[1][2]
- Yes, inspected; recorded hostname is this host → On this host, is the restic process that owns the recorded local lock still running?
- Yes, inspected; recorded hostname is a different host → On the recorded remote hostname, is the restic holder process still running?
- No, lock metadata was not inspected → Collect a restic lock evidence packet
- On the recorded remote hostname, is the restic holder process still running?
Check for the recorded PID on the recorded remote hostname, not only on the local host. The lock metadata identifies the holder by hostname and PID; the restic References design documentation allows multiple hosts to access the repository in parallel. If the remote holder cannot be checked, the lock cannot be classified as stale.[1][2]
- Yes, the remote holder is still running → Wait or coordinate; the lock is active
- No, no holder process is running on the recorded remote hostname → Has the identified conflicting lock been confirmed stale after the holder check?
- Cannot check the recorded remote hostname → Collect a restic lock evidence packet
- On this host, is the restic process that owns the recorded local lock still running?
This question applies only after the conflicting lock metadata was inspected and the recorded hostname is this host. Inspect running processes and the scheduler for the recorded PID and repository. The restic stable manual documents the unlock command as removing locks other processes created; it is not appropriate while the legitimate holder is still running. Do not use absence of an unrelated local process as proof that a remote-held lock is stale.[1][2]
- Yes, the recorded holder is still running → Wait or coordinate; the lock is active
- No holder process is running on this recorded hostname → Has the identified conflicting lock been confirmed stale after the holder check?
- Cannot determine the holder state → Collect a restic lock evidence packet
- Has the identified conflicting lock been confirmed stale after the holder check?
Proceed only after the holder check on the recorded hostname, whether local or remote. Confirm that the failing run was interrupted or that no holder process owns the identified conflicting lock on that hostname. The restic stable manual documents the unlock command as the supported way to remove locks other processes created.[1][2]
- Yes, the identified conflicting lock is stale → Use the documented unlock command
- No, the identified lock may still be in use → Wait or coordinate; the lock is active
- Stale state cannot be confirmed → Collect a restic lock evidence packet
- Wait or coordinate; the lock is active
Allow the legitimate holder process on the recorded hostname to finish, or stop it through the documented control flow of the system that started it. The recorded hostname may be a different host that targets the same repository. Consider the --retry-lock flag in wrapper scripts to wait for a configured duration before reporting the error. Do not invoke unlock while a legitimate holder still owns the identified conflicting lock.[1][2]
- Use the documented unlock command
Invoke restic unlock against the same repository only after identifying the conflicting lock, inspecting its hostname, PID, exclusive state, and time, and confirming that no holder process owns it on the recorded hostname, including a different host when the lock metadata names one. The restic stable manual documents unlock as the supported way to remove locks other processes created. Do not delete lock files in the repository by hand.[1][2]
- Collect a restic lock evidence packet
Preserve the exact restic exit code, command, repository, host, scheduler entry, timestamps, lock ID, and inspected lock hostname, PID, exclusive state, and time. Send the sanitized evidence to the operator or maintainer; the restic stable manual does not describe removing a lock whose holder or origin cannot be identified.[1][2]
- Investigate the actual restic error or repository state
Match the current exit code against the restic stable manual. Exit 10 means the repository does not exist; exit 12 means the password is incorrect; exit 1 is a fatal error without a snapshot; exit 3 means some source data could not be read. A backend connection or permission problem needs its own investigation.[1]
Detailed diagnosis
1. Classify the response by exit code
Match the captured exit code and message to the documented restic stable manual semantics. A reached restic reporting an already-locked repository is distinct from a non-existent repository, an authentication failure, a backend connection error, or a partial-source error. If the error is not exit 11, leave this page.[1]
2. Check whether another restic process is still active
Inspect the conflicting lock metadata with restic list locks and restic cat lock <lock-id>, including time, exclusive state, hostname, username, PID, uid, and gid. Then inspect running processes and scheduled jobs on every host that targets the repository, including the hostname recorded in the lock. The restic stable manual documents the unlock command as removing locks other processes created; it is therefore not appropriate while a legitimate holder still owns the conflicting lock. Parallel or overlapping jobs are permitted when their locks do not conflict; they are not automatically stale locks.[1][2]
3. Distinguish a stale lock from an active one
If the lock metadata shows a hostname that is not the current host, check for a running restic process on that remote host before declaring the lock stale. A lock without a running restic process on the recorded hostname, or from an interrupted previous run, is a candidate for the documented unlock command. The restic stable manual frames the unlock command as the supported way to remove locks other processes created; it does not authorize deleting lock files by hand. If the presence of an active process is uncertain, do not invoke unlock.[1][2]
4. Check for overlapping scheduled or manual runs
Compare the timestamp of the failing run with the scheduler entry and any recent manual invocations on every host that targets the repository. The restic stable manual documents the --retry-lock flag, which a script can use to retry locking the repository for a configured duration when it is already locked; this is a scheduling response, not a way to remove a lock. Parallel jobs are permitted when their locks do not conflict; review the schedule only when the conflict is confirmed.[1][2]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
A legitimate restic operation is holding the conflicting lock
The restic References design documentation states that the repository allows parallel access and that locks are exclusive or non-exclusive. A second operation that arrives while a conflicting lock is held is refused with the documented exit status. Parallel operations are permitted when their locks do not conflict.[2]
How to check: Inspect the lock metadata with restic cat lock <lock-id> and verify whether the holder is still running on the recorded hostname or on another host that targets the repository.[2]
A previous restic run was interrupted and left a stale lock
An interrupted backup, check, prune, or forget can leave a lock behind. The restic stable manual documents the unlock command specifically as the supported way to remove locks other processes created.[1]
How to check: Inspect the lock metadata, verify no restic process is using the repository on the recorded hostname or any other host that targets it, then invoke the documented unlock command from the same repository the failed command targeted.[1][2]
An automated job overlaps with another run and conflicts
Two restic invocations against the same repository that overlap in time may contend for the lock, but the References design documentation allows parallel instances and even parallel writes with multiple non-exclusive locks. The conflict depends on the exclusive state of the existing lock, not merely on time overlap.[1][2]
How to check: Review the scheduler entry and any other host that targets the same repository. Use the lock metadata to confirm whether the overlap actually produced a conflicting lock before coordinating the schedule or relying on --retry-lock alone.[1][2]
Next actions and procedure boundaries
If a legitimate run is active: wait or coordinate
Allow the active restic process to finish, or stop it through the documented control flow of the system that started it. The restic stable manual documents the --retry-lock flag, which a wrapper can use to wait for a configured duration before reporting the error. Do not invoke unlock while a legitimate process is still using the repository, including on another host that targets the same repository.[1][2]
If the lock is stale: use the documented unlock command
After inspecting the lock metadata with restic list locks and restic cat lock <lock-id> and confirming no restic process is using the repository on the recorded hostname or any other host that targets it, invoke the documented unlock command against the same repository. The restic stable manual documents unlock as the supported way to remove locks other processes created. Do not delete lock files by hand; the manual does not describe that operation.[1][2]
restic unlockFor an overlapping schedule: adjust the job, not the lock
Change the scheduler entry, the host that runs the job, or the repository so that two restic operations do not target the same repository at the same time when their locks conflict. The restic stable manual documents the --retry-lock flag, which a script can use to wait for a configured duration before failing; this is a wrapper behavior, not a lock removal mechanism. Do not introduce a wrapper that runs the command before the lock is acquired; the manual documents locking as part of repository-mutating operations. Parallel jobs are permitted when their locks do not conflict; review the schedule only when the conflict is confirmed.[1][2]
Do not use --no-lock to bypass writes
The restic stable manual documents the --no-lock flag as allowing some operations on read-only repositories; it is not described as a general workaround for a locked repository. A repository that is being modified by another operation is not a read-only repository, and disabling the lock for a write is not supported by the documented flag.[1]
If the lock cannot be classified: preserve evidence
Keep the restic exit code, command, repository, host, scheduler entry, and timestamps. Send the sanitized evidence to the operator or maintainer before any further action; the restic stable manual does not describe a procedure for removing a lock whose origin cannot be identified.[1]
Before any separately scoped scheduling or automation change
Planning boundary only. The operator must consider the current backup schedule, the other hosts that target the repository, and the protection policy. This page does not delete the repository, remove the local cache, change the password, rewrite the scheduler entry, or otherwise alter backup protection.[1]
Before changing anything
- Risk
- Changing the backup schedule or automation can leave the repository unprotected or cause repeated contention without addressing the actual lock state.[1]
- Safer check
- First confirm the documented exit code and the presence of an active restic process. Do not delete the repository or remove the local cache to bypass the lock.[1]
- Expected result
- A later owner-approved scheduling or automation change must leave the repository lock-free for the next run and must not weaken the protection policy. A new schedule alone does not prove the lock is gone.[1]
- Backup / recovery access
- The operator must preserve the current scheduler entry, the repository configuration, the password file, and the local cache before any change. Establish an independent recovery path that does not depend on the schedule being modified.[1]
- Rollback
- No universal scheduling or automation rollback is supplied. Require an installation-specific restoration plan from the operator. If the next run cannot complete after the change, restore the previous scheduler entry before further investigation.[1]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-06. Reachability and automated validation do not replace editorial verification of each claim.
- restic stable manual
restic project · Tier A · accessed 2026-09-06 - restic References: design, repository format, locks, and object inspection
restic project · Tier A · accessed 2026-09-06 - restic GitHub releases
restic project · Tier B · accessed 2026-09-06