Why Does a Restic Backup Stall When Another Host Starts Pruning?
The backup usually stalls because prune needs exclusive control of the shared repository, so the second host cannot continue through the same repository state at that moment.
In a multi-host home setup, the timing is the best first discriminator: the backup progresses normally, another machine starts prune, and the backup then waits or reports a lock. Confirm the lock owner and active maintenance log before touching anything. Let prune finish or stop it cleanly from the owning host; never remove its lock from the waiting backup client.
Confirm That Prune Is the Exact Trigger
Save the waiting backup log and the pruning host's maintenance log with timestamps. List repository locks and match the host, process, and exclusive state to the prune job. The cause is supported when backup progress stops after prune acquires the repository and resumes after that lock is released.
Operators using one repository from several hosts report lock contention during pruning because the maintenance operation competes with otherwise independent backup schedules.
If the backup was already slow, the prune host never obtained a lock, or both logs stop at a storage error, do not force this diagnosis. Check backend availability, latency, and the backup process itself. The prune-lock explanation applies only when the trigger, lock owner, and release timing agree.
Treat the Exclusive Lock as a Safety Boundary
Prune changes repository storage and therefore needs a consistent view while it works. The waiting backup is not necessarily hung in the ordinary process sense; it may be respecting the maintenance lock. The first question is whether prune is making progress, not how to make the backup ignore the lock.
A shared-repository design needs one maintenance owner because repository-wide maintenance affects every client even when the source data belongs to different hosts.
If prune logs advance and repository I/O continues, leave the lock in place and let the job finish. If the job is genuinely stuck, stop it gracefully from the host that owns it and wait for a clean exit. Removing the lock from another client while prune still writes converts a controlled wait into an unsafe overlap.
Recover the Waiting Backup Without Bypassing Locking
The least invasive fix is to wait for prune to complete. If the backup has a bounded retry policy, let it retry after the exclusive lock disappears. When prune must be stopped, use its service manager or process supervisor on the owning host, wait for shutdown, and confirm the lock list changes before restarting the backup.
Retention may be scoped by host, but physical reclamation is still repository work. A host-scoped retention policy prevents the wrong snapshots from being selected; it does not make simultaneous prune safe for unrelated backup clients.
Retry the waiting backup with ordinary locking. If it completes, the repair matches the confirmed cause. If another prune starts immediately, disable the duplicate maintenance schedule. If the backup still stalls with no exclusive lock, stop increasing retries and return to backend, network, source-scan, or process diagnostics.
Re-Test the Original Overlap and Define the Boundary
Use a controlled window with full logs. Start a normal backup, then invoke the planned maintenance controller and confirm it does not create an unsafe overlap. Repeat in the intended order with prune first and verify that the backup waits or exits under the configured policy, then succeeds after the lock releases.
If an interrupted prune leaves the repository in a different operational state, follow the interrupted-prune diagnosis rather than treating every later failure as ordinary contention.
Recovery passes when the original overlap is handled predictably, the backup later completes, prune exits cleanly, and a sample snapshot remains restorable. Escalate if the lock never refreshes or releases, multiple hosts keep starting maintenance, or a repository check reports damage. Those results exceed the single live-prune cause.
Recommended products
Support & Tips
More to Read
How to Schedule Restic Backup, Forget, and Prune Jobs Without Lock Conflicts
A complete multi-host Restic schedule that separates frequent backups, scoped retention, physical prune, checks, retries, and restore validation.
How to Prevent Restic Prune Jobs From Blocking Scheduled Backups
A prevention plan for shared Restic repositories that separates backup windows from prune and keeps locking, retries, and alerts intact.
How to Clear a Stale Restic Lock Without Interrupting an Active Backup
A least-invasive Restic unlock workflow that protects active backups, removes only stale state, and confirms recovery under the normal schedule.
