restic unlock
Restic uses "Lock Files" to prevent multiple processes from modifying the repository at the same time (e.g., you cannot run two prune operations simultaneously). If a Restic process crashes, is killed, or loses network connectivity, it may leave a "stale" lock file behind. restic unlock safely removes these stale locks.
unlock is the fix for the error: repository is locked by [PID] on [HOST]. If no Restic process is actually running on that host, you need to clear the path for the next operation.
Basic Syntax
restic unlock [flags]
Usage Step
# Force unlock all stale locks in the repo
restic unlock
Key Flags
| Flag | Description |
|---|---|
--remove-all | Remove ALL locks, even those that appear to be active (Use with extreme caution) |
When to Use Unlock
| Scenario | Recommendation |
|---|---|
| Normal Interruption | If you Ctrl+C a backup, it usually cleans up its own lock. No unlock needed. |
| System Crash | If the server reboots during a backup, a lock will remain. Unlock required. |
| Network Failure | If the connection to S3/SFTP drops during a prune. Unlock required. |
| Running Backup | If a backup is currently running, the repo should be locked. DO NOT UNLOCK. |
The Danger of --remove-all
The --remove-all flag is a nuclear option. In a multi-user environment, or a server with multiple cron jobs, another machine might be legitimately backing up to the same repo.
If you run restic unlock --remove-all while a prune or backup is actively running from another machine, you risk repository corruption or data loss. Only use this if you are 100% sure no other restic processes are touching the repository.
Practical Workflow
- Check Processes: Ensure no
resticprocess is running on the local or remote machines.ps aux | grep restic - Attempt Backup: If it fails with a lock error, note the ID, Host, and PID provided in the error message.
- Run Unlock: Clear the stale locks.
restic unlock - Confirm: Run your backup again.
Examples with Output
Examples with Output
1. Typical Unlock (Safe)
This removes locks that are older than 30 minutes (stale). Command:
restic unlock
Output:
repository a7b2c9d opened successfully, password is correct
successfully removed 1 locks
2. Unlock When No Locks Exist
Command:
restic unlock
Output:
repository a7b2c9d opened successfully, password is correct
successfully removed 0 locks
3. Dealing with a Locked Repository Error
Command:
restic backup /home
Output:
repository a7b2c9d opened successfully, password is correct
Fatal: unable to create lock in backend: repository is already locked by PID 1234 on host app-01 by root (UID 0, GID 0)
lock was created at 2024-01-01 12:00:00 (10m0s ago)
storage ID 58f2d1c9
the `unlock` command can be used to remove stale locks
4. Force Unlock (Nuclear Option)
Use this if restic unlock says it can't remove locks because they appear fresh, but you know the process is dead.
Command:
restic unlock --remove-all
Output:
repository a7b2c9d opened successfully, password is correct
successfully removed 3 locks
5. Automated Unlock in Script
Command:
restic unlock || echo "Failed to unlock"
Output:
repository a7b2c9d opened successfully, password is correct
successfully removed 0 locks
What's Next?
After unlocking, it's a good practice to run restic check to ensure the interrupted process didn't leave the repository in a broken state.