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.
Borg takes a lock on the repository, and another one on the local cache, before it works. This error means it could not get one. If the message ends in "(timeout)", another process holds a conflicting lock and did not let go within --lock-wait (default: 1 second). If an operating-system error appears in brackets instead, Borg could not create its lock files at all.
Borg removes a stale lock by itself only when the lock was made by the same host identity and that process is gone. A lock made under any other host identity is assumed to be alive. borg break-lock is the right answer only after you have shown that no Borg process on any machine is using the repository or the cache.
What the error means
Borg documents two messages in its list of message IDs: "Failed to create/acquire the lock {} (timeout)." (modern exit code 73) and "Failed to create/acquire the lock {} ({})." (modern exit code 72). Unless BORG_EXIT_CODES is set to "modern", Borg returns 2 for every error.
How the lock works. The documentation says the locking system "is based on renaming a temporary directory to lock.exclusive". Inside that directory a file records the "hostname, process id and thread id of the lock holder", and a JSON file lock.roster lists all shared and exclusive lockers. The repository lock is repository/lock.*; the cache lock is "usually in ~/.cache/borg/REPOID/lock.*".
Which commands take which lock. The 1.4.5 source marks create, prune, compact, check and delete as exclusive. list, info and extract take a shared lock, so a long read blocks a writer. The FAQ states the result: "Borg uses a repository-wide lock. Only one process can have write access at a time. If multiple backups are triggered simultaneously, they will wait for the lock (see --lock-wait) or fail."
Which lock failed. The message prints the lock's path, and the source shows what each path means. A path ending in lock.exclusive means the exclusive lock is held (Borg also takes it briefly while it updates the roster). A path ending in lock means you asked for exclusive access while shared holders were active. A path under ~/.cache/borg/ means the cache lock, which belongs to one machine and one user.
What counts as stale. In the 1.4.5 source, the lock holder's name is split into host identity, process ID and thread. If the host identity matches this host and the process is dead, Borg deletes the lock and logs "Killed stale lock". If the host identity is different, the holder is treated as alive and the lock stays. The host identity is built from the fully qualified name and the network card's address (fqdn@MAC), unless you set BORG_HOST_ID. The documentation says an unstable identity "kills automatic stale lock removal".
Borg's changelog lists a fix for signal handling (SIGINT, SIGTERM, SIGHUP) that avoids leftover lock files, since 1.0.8rc1. Signals that cannot be handled, such as kill -9, a crash or a power loss, are therefore the more likely way for a lock to be left behind.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| A job is genuinely running, or two jobs overlap | "(timeout)"; the lock names a live process on a known host | Read the file in lock.exclusive; look for that process on that host |
| A long read holds a shared lock | A backup fails while borg list, info or extract runs |
Path ends in lock; lock.roster lists shared holders |
Hung borg serve on the repository server |
Repeated failures after a network drop; the holder is on the server | The process in the lock name still exists there; the ssh session is dead |
| The lock was made under a different host identity | Error persists with nothing running here; no "Killed stale lock" | Host part of the lock name differs from this machine's identity |
| Killed job on the same host identity | One failed run, then it clears itself | Warning "Killed stale lock" in the next run's log |
| Lock files cannot be created | Message ends with an operating-system error, not "(timeout)" | The error text; write access, free space, read-only storage |
| Malformed lock name | Log: "Found malformed lock ... Please check/fix manually." | That log line |
| Repository copied while locked | The lock appears on the copy | Borg's with-lock note: a copy keeps the lock |
Prove the cause before changing anything
Read the lock rather than guessing. These are plain file listings of locations Borg documents. For a remote repository, do this on the repository server.
ls -l /srv/backup/repo
ls /srv/backup/repo/lock.exclusive
cat /srv/backup/repo/lock.roster
Do not use borg list or borg info to inspect: they need a lock too, and fail the same way. --bypass-lock exists, but the documentation says it is for storage that is read-only, and that with it "you are responsible for ensuring that no other Borg instances have write access". It is not an inspection tool.
A lock name has the form <host identity>.<process id>-<thread>. From the source, the thread is always 0, and the host identity is <fully qualified name>@<number>. Read it from the right: the digits after the last - are the thread, the digits after the last . are the process ID, and the rest is the host identity.
Then decide in this order:
- Which host? If the name is another machine, go to that machine. Do not decide from the one you are standing on.
- Is that process alive there, and is it Borg? A live Borg process with a start time inside your longest normal job is a running job. Wait, or fix the schedule.
- Is it a stuck
borg serve? The Borg documentation describes it: when the connection "is disconnected or stuck abnormally", sshd keeps running, "and as a result so does the borg serve process holding the lock on the repository. This can cause subsequent borg operations on the remote repository to fail with the error: Failed to create/acquire the lock." - No such process, and the host identity is not this host's? The lock is stale but Borg will not remove it. This is the case
break-lockis for. - Also check the cache lock. The repository lock and the cache lock are separate. Another user or process on the same machine may hold the cache.
Example (illustrative): fs01 backs up over ssh to backup01, repository /srv/backup/repo. A network blip at 02:20 drops the session. At 02:00 the next night the job fails with "Failed to create/acquire the lock /srv/backup/repo/lock.exclusive (timeout)". On backup01, ls /srv/backup/repo/lock.exclusive shows one file, backup01.example.net@123456789012.4821-0. Process 4821 on backup01 is still a borg serve, now about 23 hours 40 minutes old (02:20 to 02:00 is 23 h 40 min). The holder is alive, so this is a hung session and not a stale lock. With the keepalive settings Borg recommends (ServerAliveInterval 10, ServerAliveCountMax 30), the same session would have ended after 10 × 30 = 300 seconds, and --lock-wait 600 would have covered the wait.
Fix
A running job or overlap
Wait for the holder. To let jobs queue instead of failing, raise the wait, for example borg --lock-wait 600 create .... Keep the maintenance jobs (prune, compact, check) out of the backup window, because they are exclusive too. The FAQ suggests one repository per client for the same reason: "This avoids lock contention".
A hung borg serve
Make the repository server drop dead sessions. Borg's serve page recommends this on the client (~/.ssh/config):
Host backupserver
ServerAliveInterval 10
ServerAliveCountMax 30
and on the server (sshd_config):
ClientAliveInterval 10
ClientAliveCountMax 30
With these, a dead connection lasts about 300 seconds, after which the server's sshd process is terminated, "causing the borg serve process to terminate gracefully and release the lock on the repository". For a session that is stuck now, ending its sshd session on the server is what releases the lock.
Risk: the sshd_config change applies to every SSH connection to that server, not only Borg's. A session that stays silent for about 300 seconds (10 × 30) is dropped, which can cut a slow but healthy connection. sshd must be told to reload its configuration before the change takes effect (use your system's own procedure). To back out, remove the two lines and reload sshd again.
Disruptive step: ending a session that is still writing interrupts a backup. Borg keeps checkpoint archives, so the next run resumes, but confirm the session is truly dead first.
A different host identity
First make the identity stable: set BORG_HOST_ID to a fixed, unique value for the account that runs the job. The documentation advises this when the automatic identity is unreliable (it names an all-zero MAC address) or you want to control it yourself. Then clear the existing lock.
Disruptive step: borg break-lock /srv/backup/repo removes the repository lock and, from the source, the cache lock on the machine you run it on. The documentation says to use it "only when no borg process (on any machine) is trying to access the cache or the repository" and warns the repository might get damaged if two processes use it together. Nothing restores a lock you remove, and cache locks held on other machines are not touched. If you broke a live lock by mistake, stop all jobs and run borg check (read-only by default). Do not use --repair without a copy: Borg calls it "POTENTIALLY DANGEROUS".
Lock files cannot be created
Fix the cause shown in brackets: write permission for the backup user, free space, or storage that does not support the atomic rename Borg relies on. The FAQ advises against network filesystems for repository storage where possible.
A copied repository
Run borg break-lock on the copy before using Borg on it from a different host. Borg's documentation says so.
Maintenance that never ran
If prune or compact was starved by the lock, space has not been returned. After the lock is clear, run them in a quiet window; deleted backups that free no space, a separate topic, covers the order.
Confirm the fix
ls /srv/backup/reposhows nolock.exclusiveorlock.rosterwhile all jobs are idle.- The next scheduled run finishes with return code 0. Add
--show-rcto log it. - With
BORG_EXIT_CODES=modern, a recurring 73 or 72 can be told apart from other errors. - A lock-free repository is not proof of a good backup; run your restore test.
What to watch afterwards
- Alert on return codes 72 and 73, and on a lock directory older than your longest job.
- Keep a timetable of backup, prune, compact and check windows per repository.
- Keep
BORG_HOST_IDfixed on hosts whose name or network card can change, such as cloned machines. - Keep the ssh keepalive settings on both ends of every remote repository.
Read next
Related articles you may want next.
- Backup & Recoveryrestic: 'repository is already locked': stale locks, running jobs and when to unlockrestic says the repository is already locked. Tell a live job from a stale lock, read the lock safely, and know what restic unlock and --remove-all remove.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
- Backup & RecoveryDeleted old backups but no space was freed: forget, prune and compact explainedDeleted backups, same disk usage? Deleting only removes references. Check the restic prune or Borg compact stage, shared blocks, locks and append-only.Read article
Risks and limits
- These commands have not been run or lab-tested. They come from the Borg 1.4.5 documentation and source.
- Which path means which lock, which commands are exclusive and how staleness is judged come from the Borg 1.4.5 source code, not from a recorded run. They may differ in other versions.
- Borg 2.x has a different repository format and different locking, and is not covered.
- A lock name is split by a rule in the source; unusual names are reported as malformed and need manual care.
break-lockcannot tell a live holder from a dead one. That judgement is yours.
Sources
- borg with-lock and borg break-lock — Borg 1.4.5 documentation
- Data structures and file formats: lock files — Borg 1.4.5 documentation
- Frequently asked questions — Borg 1.4.5 documentation
- borg serve: SSH configuration — Borg 1.4.5 documentation
- Common options, environment variables and return codes — Borg 1.4.5 documentation
- Message IDs — Borg 1.4.5 documentation
- borg check — Borg 1.4.5 documentation
- Borg change log — Borg 1.4.5 documentation, 1.4.5 dated 2026-07-19
- Borg 1.4.5 source: locking.py — Borg project
- Borg 1.4.5 source: platform/posix.pyx, platform/base.py, archiver.py, repository.py, cache.py — Borg project
This article was originally published on .