borg check failed "inconsistent manifest"

TL;DR

Stop all Borg jobs against the repository first and copy or snapshot the repository as it stands before touching repair options. Check whether two writers, an interrupted transaction or an unclean shutdown explains the manifest mismatch, run borg check in read only mode again to confirm, and use repair only as a deliberate last step on the preserved copy. Most manifest problems start as access or interruption problems, not lost archives.

borg check failed "inconsistent manifest"

Use this when

• borg check reports an inconsistent manifest, manifest does not match, or similar integrity wording.
• A Borg backup or prune was interrupted by a power loss, kill or full disk.
• Two hosts or two schedules may be writing to the same Borg repository.

Not for this skill when

• A single archive is missing files the source never had. That is a create selection problem, not repository consistency.
• The repository disk has confirmed read errors across many files. Image the disk and plan recovery before Borg repair work.
• You use restic or Kopia. Their manifest and index repair flows are different tools.

Steps

1. Freeze the repository: disable Borg schedules, confirm no borg process holds the repository lock on any host that can reach it, and leave the existing lock handling to Borg rather than deleting lock files by hand while a process may still run. Record who or what last wrote to the repository and when it stopped. Verify: no active borg process exists for the repository and you have a timeline of the last create, prune or check that touched it
2. Preserve the state by taking a filesystem snapshot or a file level copy of the whole repository directory to separate storage before any repair flag is used. Borg repair can discard inconsistent entries, and the preserved copy is your way back if it discards the wrong thing. Verify: a complete preserved copy or snapshot of the repository exists and its size matches the original within expected tolerance
3. Run borg check without repair and with verbose output, and save the full output. Note whether the complaint is only about the manifest and transaction state or whether segment and archive errors also appear, because manifest only findings after an interruption are treated differently from widespread segment damage. Verify: the saved check output separates manifest findings from any segment or archive errors and can be compared after each later step
4. Investigate the interruption and concurrency causes the output suggests: check disk full events, host shutdown logs, NFS or network filesystem behaviour if the repository sits on one, and whether a second host has the same repository configured. Borg repositories expect a single writer at a time and a reliable local or ssh filesystem. Verify: you can point to a concrete interruption or concurrent writer, or rule both out with logs from the time of the first failed check
5. If the findings are manifest only and the preserved copy exists, run borg check with the repair option during a maintenance window and read exactly what it proposes or reports fixing. Immediately rerun a read only check and list archives, comparing the archive list with your catalog records before resuming schedules. Verify: the follow up read only check passes, borg list shows the expected archives, and a test extract of a small file from a recent archive succeeds
6. Fix the root cause before re enabling jobs: separate repositories per host, move the repository off an unreliable network mount, add disk space alerting, or sequence prune so it cannot overlap create. Run the next create and check cycle under observation. Verify: a full create followed by a read only check completes cleanly with no other writer active

Why it happens

Borg stores repository state in a manifest that must agree with the transaction log and segment data. An interrupted write, a killed prune, a full disk mid transaction, or two writers updating the repository can leave the manifest describing a state the segments have not fully reached, or the reverse. Borg check detects that disagreement and reports inconsistency rather than guessing. Because repair reconciles by discarding or rolling entries, running it immediately without a preserved copy and without finding the interruption cause can lose recent archives and still leave the underlying concurrent writer ready to break it again.

Variants and edge cases

Security related manifest warnings after moving a repository to a new location are a different path: Borg asks to confirm the new location because the manifest and security info moved. Do not confuse a location confirmation prompt with corruption, and do not approve it casually if the move was not planned. Also, append only and key mode changes have their own checks; document the repository mode before repair so it is restored correctly.

borg check inconsistent manifest after power loss

The interruption variant. Expect a manifest and transaction mismatch from the cut off write; preserve, check, then repair deliberately.

borg manifest does not match after two hosts backed up to same repo

The concurrent writer variant. Repair alone will not hold; split repositories or enforce a single writer with locking and scheduling.

borg check errors found but archives list fine

Use when listing works but check complains. The detail lines decide whether this is manifest bookkeeping or real segment damage, so save and read the full output.

Provenance

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

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

Thread query: borg check failed "inconsistent manifest"

TL;DR: Stop all Borg jobs against the repository first and copy or snapshot the repository as it stands before touching repair options. Check whether two writers, an interrupted transaction or an unclean shutdown explains the manifest mismatch, run borg check in read only mode again to confirm, and use repair only as a deliberate last step on the preserved copy. Most manifest problems start as access or interruption problems, not lost archives.