borg backup failed "LockError: Failed to acquire lock"

TL;DR

Find the lock holder before breaking anything: Borg stores the locking host and process in the repository lock, and a live holder means a backup, prune or check is genuinely running. Check that host and process, wait or stop it properly, and use break-lock only for a holder you have proven is gone. Breaking a live lock lets two writers corrupt the same repository.

borg backup failed "LockError: Failed to acquire lock"

Use this when

• borg create, prune or check fails with LockError failed to acquire lock.
• A Borg process was killed, a host crashed, or an ssh session dropped mid job.
• Backups and maintenance jobs for one repository overlap in the schedule.

Not for this skill when

• The lock holder is a long running legitimate prune that still progresses. Let it finish rather than breaking its lock.
• Borg cannot write the repository at all because the filesystem is read only. That is a storage fault, not a lock dispute.

Steps

1. Read the lock details Borg prints with the error and any lock information in the repository, noting the host name and process id it claims. That pair, not the error line alone, decides whether the lock is live or stale. Verify: you have the locking host and process id recorded
2. On that host, check for that process and for any Borg process at all, including jobs started by cron, systemd and ssh forced commands from other hosts sharing the repository. Verify: the claimed process is confirmed running or confirmed absent on its own host
3. If a holder is running, decide properly: let it finish if it progresses, or stop that job through its own service or session so Borg removes its lock on exit. Do not stack a second backup behind it by force. Verify: the running job ends and the lock clears on its own
4. Check repository hosting factors that fake a stale lock: a network filesystem with stale handles, a repository host that slept, or clock jumps can make a dead lock look defended. Confirm the repository filesystem is mounted normally and other files can be created beside the repository by the backup user. Verify: a test file can be created and removed next to the repository
5. Only with the holder proven absent, run borg break-lock for that repository exactly once, using the same repository setting the jobs use, then immediately run a read only list. If break-lock is needed again the same week, treat that as a scheduling bug still to find. Verify: break-lock completes and borg list returns archives
6. Separate the schedules that collided: backups, prune, compact and check for one repository must not run at the same time, so chain maintenance after backups in one job script or add a simple file lock wrapper around all of them. Verify: a backup followed by prune in sequence both succeed with no lock error

Why it happens

Borg allows one writing process per repository and enforces it with a lock that records which host and process holds it, because concurrent writers would race on segments and the index. The lock is released on clean exit, so crashes, killed ssh sessions and powered off hosts leave it behind. Other backup tools sharing the folder, and overlapping maintenance timers, create genuine contention that looks identical. The fix is therefore identification first and break-lock last. Compatibility: BorgBackup 1.2 and 1.4, local, ssh and network filesystem repositories, including append only and shared repository setups.

Variants and edge cases

LockError after ssh connection dropped

The Borg server process on the repository host can outlive the dropped client session. Check for and end that orphaned server process on the repository host before using break-lock.

Failed to acquire lock on NFS repository

NFS can delay lock visibility between hosts. Prefer running Borg on the host that stores the repository, or serve it over ssh, rather than several clients locking over NFS.

lock held by unknown host

An unknown host name usually means an old container or a renamed machine held the lock. Match it against decommissioned hosts, prove it is gone, then break the lock and document the host name.

Provenance

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