Troubleshooting and migration

Use this reference for failed jobs, locks, repository errors, damaged metadata, backend changes, or copy/migration work.

Diagnose in order

Capture the exact restic command, version, exit status, and bounded stderr. Redact passwords, tokens, signed URLs, and private paths before sharing.
Separate source failures from repository/backend failures. A permission-denied source path, an expired S3 credential, and a corrupt index have different owners and remedies.
Reproduce with a read-only command if possible: snapshots, stats, check, or a limited ls.
Check for an active restic process before manipulating locks.
Read the installed command's --help and the matching stable documentation before a repair or migration command. These operations are version- and repository-state-sensitive.

Symptom map

Symptom	Evidence first	Do not do
Password/repository cannot open	Confirm repository URL, password source readability, backend identity, and exact error	Do not initialize the same target again
Permission denied	Identify source versus backend, execution user, file mode/ACL, and provider policy	Do not broaden permissions globally as a first fix
Locked repository	Process list/job scheduler, lock age, known concurrent maintenance	Do not immediately run `unlock`
Slow or timed-out job	Source scan, backend latency, bandwidth, lock contention, logs	Do not change many performance flags at once
Backup had errors	Examine failed source paths and whether snapshot policy allows partial backups	Do not call the backup healthy from exit code alone
`check` failure	Exact check error, version, backend health, last good restore	Do not run repair blindly
Need new storage backend	Destination compatibility, credentials, capacity, copy/restore test	Do not delete old repository after a copy-only claim

Locks

Restic uses repository locks to protect concurrent operations. A running backup, prune, check, or interrupted process can leave a lock. Establish whether an operation is active through the scheduler and process list; only then consider restic unlock for a stale lock. If the host may have crashed or the backend is eventually consistent, document the evidence and retry conservatively.

Repository repair and index work

Commands such as rebuild-index, repair, migrate, and recover exist for specific conditions. They are not routine maintenance. Before invoking one:

Preserve the exact error and restic version.
Run the least-invasive documented diagnostic first.
Confirm a second copy or tested recovery point where feasible.
Read the corresponding command help for the installed release.
Verify afterward with check and a restore test.

Do not invent a repair sequence based on a search snippet. Repository state and restic version determine the valid path.

Documented repair posture

For a reported integrity failure, stop retention/prune jobs and preserve the current evidence before repair. The troubleshooting documentation's general sequence is: run check --read-data; make a copy of the repository metadata at minimum (especially index/ and snapshots/); run repair index when check suggests it; rerun backups if overlapping source data can replenish missing content; run repair snapshots --dry-run; then decide whether repair snapshots --forget is an acceptable, explicit data-loss action; finally run another full check and a restore test.

repair packs and repair snapshots are remediation commands, not health checks. They can change what remains recoverable. Do not automate them, and never describe repair as successful without a post-repair check plus a restore of the relevant data.

Copy and migration

restic copy copies snapshots between repositories. It is not a substitute for a recovery verification. For a migration:

Inventory source snapshots and repository/client versions.
Initialize and secure the destination independently.
Copy a small representative scope first if the command/backend supports it.
Compare source and destination snapshot inventory.
Run destination check and restore a representative snapshot from the destination.
Keep the source immutable/available until the agreed retention period and recovery drill are complete.

A backend move may require moving credentials, lifecycle policy, monitoring, and recovery documentation as well as data. Update all of them.

For copy, source and destination use distinct credential namespaces (RESTIC_FROM_REPOSITORY, RESTIC_FROM_PASSWORD_FILE, and related RESTIC_FROM_* variables for the source). Different repository encryption keys require data to be downloaded and uploaded. If cross-repository deduplication matters, initialize a new destination with init --from-repo SOURCE --copy-chunker-params before writing it; chunker parameters cannot be changed later. These details make the copy path a migration project, not a one-line storage move.

Version compatibility

Repository format and client version are related but not interchangeable. The stable documentation identifies repository format version 2 as the current default and states its minimum restic version. Before upgrading automation, pin and test the candidate client against a non-production repository or a representative restore. Review the project's release notes for behavior changes, especially around commands used unattended.

Evidence bundle for escalation

Provide only:

restic version:
backend class (not credentials):
operation and redacted flags:
exit code:
timestamp/timezone:
first relevant stderr lines:
active-job/lock evidence:
last known-good check and restore-drill dates:

This is enough to diagnose most issues without disclosing keys or a full infrastructure inventory.

Sources

Restic command reference: https://restic.readthedocs.io/en/stable/manual_rest.html (accessed 2026-07-15)
Working with repositories and lock-related commands: https://restic.readthedocs.io/en/stable/045_working_with_repos.html (accessed 2026-07-15)
Restic release notes: https://github.com/restic/restic/releases (accessed 2026-07-15)
Restic changelog: https://github.com/restic/restic/blob/master/CHANGELOG.md (accessed 2026-07-15)

6.2 KiB Raw Blame History