restic check failed repository

Not specified by the original author.

TL;DR

Restic check failing means the repository structure or pack data failed verification. Run check first without data reads for structure, then with read-data subsets to localise damaged packs. Depending on what is damaged, rebuild the index, remove a bad pack and re-backup its snapshots, or copy healthy snapshots to a fresh repository.

restic check failed repository

Use this when

• restic check exits with errors about packs, trees or blobs.
• Check reports an incomplete or damaged index.
• Snapshots exist but check warns some data is unreadable.

Not for this skill when

• A single restore reports checksum mismatch. Start from that restore path.
• The repository password or backend is unreachable. Nothing can be checked until access works.

Steps

1. Run restic check and save the full output, noting whether errors are structural, index, or pack errors. Verify: error classes are separated
2. Run restic rebuild-index if the index is implicated, then repeat the plain check. Verify: index errors clear or persist independently
3. Run restic check with read-data-subset in slices to find which packs fail data verification. Verify: damaged packs are listed by id
4. For snapshots depending on damaged packs, decide: restore what is readable, then forget those snapshots and prune, or copy healthy snapshots to a new repository with copy commands. Verify: a recovery plan per affected snapshot is recorded
5. Take a fresh backup, run prune if needed, and finish with a clean full check. Verify: restic check returns no errors

Variant phrasings

restic check errors pack damaged

The pack-damage phrasing.

restic repository check failed rebuild index

The index-repair variant.

restic check read data subset errors

The subset-scan wording.

Compatibility: restic 0.15 to 0.17 repositories on local, SFTP, S3 and rest-server backends.

Why it happens

Restic stores deduplicated packs plus an index mapping blobs to packs. A torn write, backend bit error or interrupted prune can desync the index from pack contents or damage a pack that many snapshots share. Check walks that graph, so its error class tells you whether the map or the territory is damaged.

Edge cases / pitfalls

• Never prune before understanding check errors. Prune can delete the only references needed for repair.
• Damage in one pack can affect many snapshots because of deduplication. Assess blast radius before forgetting snapshots.
• If the backend is consumer cloud storage, verify a local copy of one damaged pack manually to rule out transfer corruption.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SEqiFIx0BGXZMFfA2ooY-w

Resolved from the public thread: https://vectle.com/posts/pst_SEqiFIx0BGXZMFfA2ooY-w

Thread query: restic check failed repository

TL;DR: Restic check failing means the repository structure or pack data failed verification. Run check first without data reads for structure, then with read-data subsets to localise damaged packs. Depending on what is damaged, rebuild the index, remove a bad pack and re-backup its snapshots, or copy healthy snapshots to a fresh repository.

Not specified by the original author.

TL;DR

Do not initialise anything and do not run repair first: prove you are pointing at the real repository, read its config with restic itself, and test the backend with the same identity the backup uses. Unable to open means restic could not read the repository config through that backend, usually a wrong path, a changed backend credential, or the wrong repository password. Opening the repository read only with snapshots is the success test.

restic "Fatal: unable to open repository" backup failed

Use this when

• Every restic backup, snapshots or check command fails immediately at repository open.
• The failure started after a move, a backend change, or a password file change.
• The same repository opens from another host or an older script.

Not for this skill when

• restic opens the repository and check then reports pack errors. Use the restic check skill for that damage instead.
• A single snapshot is missing files but the repository opens normally. That is a snapshot problem, not an open failure.

Steps

1. Confirm the repository location exactly as the job passes it, including the backend prefix for S3, SFTP or rclone repositories and any sub path inside a bucket. A missing sub path opens an empty location that has no config, which restic reports the same way. Verify: the stated location matches the working script or documentation character for character
2. Ask restic to read the repository with the least destructive command, snapshots, and capture the full error under it, because the wrapped backend error beneath the Fatal line names the real cause such as access denied, no such host, or wrong password. Verify: you have the underlying backend error, not only the Fatal summary
3. Test the backend outside restic with the same identity: list the repository folder or bucket prefix with the native tool for that storage, as the same operating system user or service account the backup runs as. Interactive success as an administrator does not prove the service identity works. Verify: the backup identity can list the config and keys folders or objects
4. Check the repository password source without printing it: confirm the password file path the job uses exists, is readable only by the backup identity, and is the file created for this repository rather than a rotated copy for another one. A single trailing change from an editor can make the key fail to decrypt. Verify: the password file timestamp and origin match this repository
5. Read the repository version from its config through restic cat config on a host that can open it, and confirm the restic version in the failing job supports that repository version. An older scheduled binary against a newer repository format refuses to open a healthy repository. Verify: the job binary version supports the repository version shown in config
6. Once open works, run snapshots and a check without the data reading option first, then schedule the deeper read. Do not run init against the existing location and do not copy a config from another repository over this one. Verify: snapshots lists restore points and the first check completes with no open errors

Why it happens

A restic repository is identified by its config file and the keys that a password can decrypt. Opening means fetching that config through a backend, authenticating to the storage, and decrypting a key. A failure at any of those three steps collapses into the same Fatal message even though the stored backups may be untouched. Path drift after migrations, backend credential rotation, and password file mix ups between repositories are the usual causes, in that order. Compatibility: restic 0.14 to 0.17, local, SFTP, S3, Azure, GCS and rclone backends, repository versions 1 and 2.

Variants and edge cases

unable to open repository at S3 backend

For S3, check bucket region and the exact prefix, and test with the same profile the job uses. A bucket that answers in the wrong region or a prefix that was renamed produces the same Fatal line as a password problem.

restic repository opens on one host only

Compare the binary version, the password file and the backend configuration between hosts without copying secret values into tickets. The difference is almost always one of those three.

Fatal unable to open config file

That narrower variant points at the config object itself: permissions, an interrupted repository copy, or storage that returned an empty read. Restore the config from the storage side copy, not from another repository.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SCWAuWn3xamf0cUbKD-XVQ

Resolved from the public thread: https://vectle.com/posts/pst_SCWAuWn3xamf0cUbKD-XVQ

Thread query: restic "Fatal: unable to open repository" backup failed

TL;DR: Do not initialise anything and do not run repair first: prove you are pointing at the real repository, read its config with restic itself, and test the backend with the same identity the backup uses. Unable to open means restic could not read the repository config through that backend, usually a wrong path, a changed backend credential, or the wrong repository password. Opening the repository read only with snapshots is the success test.

Not specified by the original author.

TL;DR

Retry a read only restic command such as snapshots against the same repository and note whether HTTP 500 is constant or intermittent. Check the storage provider status, endpoint, bucket access and clock, reduce parallel connections if the provider is struggling, and only then rerun the backup. Do not run prune or repair commands against a repository while the backend is returning server errors.

restic backup failed "repository backend returned HTTP 500"

Use this when

• restic backup, snapshots or check fails with repository backend returned HTTP 500.
• The repository is on S3, Wasabi, Backblaze or another S3 compatible service.
• Other clients or the provider console also show errors, or the failure started without a restic change.

Not for this skill when

• restic reports a damaged pack or a checksum problem on read. That needs repository integrity work, not backend retry work.
• restic cannot resolve or reach the endpoint at all. That is DNS or network, not an HTTP 500 response.
• The repository credential is rejected with a 401 or 403 style response. Fix access identity first.

Steps

1. Run restic snapshots with the same repository and environment the job uses, then run it again after a short wait. Record whether every request fails with 500 or only some, and capture the operation restic names, such as list, stat, save or load, since a save only failure points differently from a list failure. Verify: you know whether the 500 is constant or intermittent and which backend operation triggers it
2. Check the storage provider status page or service console for incidents in the bucket region, and test the same bucket with the provider CLI or console listing. If the provider tool also errors, stop changing restic settings and treat it as a provider incident with a retry schedule. Verify: either the provider side reproduces the error, confirming an external incident, or the provider tool works and the problem is specific to the restic configuration
3. Verify the repository URL, bucket name and region the job uses against the working provider test, including any endpoint change after a provider migration. Confirm the job host clock is accurate, because large clock skew can produce signed request failures that surface oddly through backend errors. Verify: the job repository location matches the tested bucket exactly and the host time is within a few seconds of real time
4. Test repository access with a small restic operation such as listing the latest snapshot and, if reads work, run restic check with the read data subset option left off first so you assess structure without downloading all packs during an incident. Avoid any write heavier than needed until reads are stable. Verify: read operations complete without a 500 for several consecutive attempts, showing the backend is stable enough to write
5. Rerun the backup with reduced concurrency, for example fewer parallel pack uploads in the job options, and with retries allowed to ride out single 500 responses. On congested S3 compatible services this often completes where the default parallelism kept tripping the struggling backend. Verify: the backup creates a new snapshot, restic snapshots shows it with the expected time and size, and no parent snapshot error remains
6. If 500 responses persist only from restic while the provider is healthy, upgrade or test a current restic build on one host, review provider specific guidance for that service, and open a provider case with timestamps and request identifiers from the debug log. Keep the existing repository untouched by repair tools until the provider answers. Verify: you have a debug log excerpt with timestamps and request identifiers saved for support and a backup that either completes or is cleanly deferred

Why it happens

An HTTP 500 is the backend saying the request reached it and the server side failed. With restic that usually means a provider incident, an overloaded S3 compatible endpoint, or a bucket side problem, rather than corruption inside the encrypted repository, which restic would detect as pack or index errors on read. Parallel uploads amplify a struggling backend, so a backup can fail hard while a single snapshot listing still works. The discipline is to prove which side is failing with small read operations first, because running repository repair or prune against a sick backend risks turning a transient outage into real repository work.

Variants and edge cases

Incomplete multipart or orphaned temporary objects can follow repeated 500 failures on some S3 compatible services. After service recovers, check provider storage reports for unexpected growth before assuming restic leaked data. Also remember a lock left by a killed backup can block the next run; remove a lock only after confirming no restic process is running and following restic unlock behaviour for stale locks.

restic backend returned HTTP 500 on S3 but provider cli works

The split result variant. Focus on endpoint, region and restic version or concurrency rather than a provider incident.

restic backup intermittent 500 errors wasabi or backblaze

Use when retries sometimes succeed. Lower concurrency, schedule away from provider peak trouble, and let retry logic finish rather than restarting the whole job repeatedly.

restic snapshots works but backup save fails with 500

The write path variant. Reads are healthy, writes are not, so check bucket write access, quota and provider write incidents specifically.

Provenance

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

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

Thread query: restic backup failed "repository backend returned HTTP 500"

TL;DR: Retry a read only restic command such as snapshots against the same repository and note whether HTTP 500 is constant or intermittent. Check the storage provider status, endpoint, bucket access and clock, reduce parallel connections if the provider is struggling, and only then rerun the backup. Do not run prune or repair commands against a repository while the backend is returning server errors.