Common Errors and Root Cause

When Restic fails, start with the basics: wrong repository and wrong password cause a large percentage of incidents.

sanity-check.sh

echo "RESTIC_REPOSITORY=$RESTIC_REPOSITORY"
echo "RESTIC_PASSWORD_FILE=$RESTIC_PASSWORD_FILE"
restic version

tip

If those variables are empty in your automation environment, your job is not loading the env file. Fix that before debugging deeper.

Symptom	Likely Cause	Action
wrong password or no key found	Bad password file	Validate RESTIC_PASSWORD_FILE and permissions
repository does not exist	Wrong repo path	Verify RESTIC_REPOSITORY path and backend
repository is already locked	Interrupted job	Confirm no active process, then restic unlock
Access denied on backend	IAM or token issue	Revalidate backend credentials and policy scope

Debug Workflow (Recommended)

1. Confirm RESTIC_REPOSITORY and RESTIC_PASSWORD_FILE
2. List snapshots
3. Run a check (subset first if you want it faster)
4. Only then attempt unlock or repair

tip

Many issues are just "wrong repository" (typo in RESTIC_REPOSITORY) or "wrong password file". Check those first.

Fast Triage Commands

restic version
restic snapshots
restic check --read-data-subset=5%

If a Job Was Interrupted

restic snapshots
restic unlock
restic check

If Backups Suddenly Stop Appearing

Check freshness:

restic snapshots --tag daily --host app-01

Common causes:

• cron/systemd job stopped running
• env file not loaded
• backend credentials expired
• repository lock from a killed job