Check restic's exit code after every forecast backup, then inspect snapshot contents and test a restore before relying on the result.
Key takeaways
- Capture the exit code immediately.
- Preserve diagnostic output separately.
- Investigate unreadable files.
- Test a restore before relying on a snapshot.
A revenue operations lead builds the model, saves it, and moves on. Weeks later, an auditor, a new analyst, or the finance chief asks for last quarter's version, and the backup is the only copy left. If the backup run quietly failed, nobody finds out until that moment.
It also reports how each run went through its exit code, a single number that your scheduler or script can read. Checking whether the job "ran," or scrolling to the last line of a log, can miss a real problem.
This post covers the three exit codes described in the restic backup documentation: 0, 1, and 3. For each one, we look at what it means, what it does not prove, and what to do next. The examples assume you run restic from a script or scheduled task on a machine that holds your forecast folder. Treat the steps as a starting point rather than a finished runbook.
Why check the exit code at all
A job that finishes is not the same as a job that saved your files. A backup can run to the end, write data, and still leave out files it could not read. Check how your scheduler handles exit codes before trusting its job result. The exit code is restic's own statement about how the run went.
Capture it right after the backup command and decide what happens next based on its value. Do not rely on a log file existing, the timestamp on the snapshot, or a tidy summary line. A summary can look fine even when the run was incomplete.
Illustrative example at quarter-end
Consider a team that backs up a forecast folder every night. On a Tuesday before the close, the nightly job runs and the scheduler marks it finished. Nobody looks at the result until the following week, when a finance director asks for the version of the model sent to the board.
Suppose the job returned exit code 3 that night. A snapshot exists with a fresh timestamp, so the listing looks normal. But a workbook could not be read, so that workbook is missing from the snapshot. The director restores the most recent copy and finds an older version. The team loses time searching, and the director loses some confidence in the archive.
Capturing the code would flag the incomplete run; the wrapper must separately preserve diagnostic output to support investigation before the close.
Exit code 0: a complete snapshot
According to the restic backup documentation, exit code 0 means the backup was successful and a snapshot with all source files was created. This is the result you want. restic read every source file it was asked to back up and recorded them.
Treat 0 as "the backup did what it was asked," not as "the backup contains everything the business needs." The backup covers only what you pointed it at. If a subfolder is missing, or a new workbook was saved elsewhere, restic will back up the folder it was given and report success. Exit code 0 checks the run, not your file layout.
A quick sanity check is still worth a minute. Confirm the newest snapshot has the time you expect, and that the path list matches the folders you intended to protect. For exports feeding that folder, use the weekly pipeline export checks.
Restore tests matter more than exit codes
Once a month, or before each close, pick one forecast file from the newest snapshot and restore it to a scratch location. Open it. Check the version, the date, and the key totals against what you expect. Then delete the scratch copy.
This test catches problems no exit code can show, such as a wrong path, a corrupted file, or a restore procedure that only works for the person who wrote it. Record the snapshot ID you tested and the date, so the next person knows what was checked.
Exit code 1: a fatal error and no snapshot
Exit code 1 means a fatal error occurred and no snapshot was created, according to the same page. Inspect available snapshots and their contents to find usable copies, including files in incomplete snapshots.
This should trigger an alert, not a quiet log entry. The forecast owner should hear about it the same day. Your wrapper should record the failure, send a notification through a channel your team actually reads, and stop reporting the run as successful.
When you investigate a 1, start with the error text printed during the run. Read the message, fix that specific cause, and rerun the backup. Confirm you get a 0 before closing the ticket.
Quarter-end timing raises the stakes. If the backup has failed silently for several nights, the last good copy may be older than anyone realizes. After any 1, check the date of your newest snapshot and tell the forecast owner that date, so they know which versions can still be recovered.
Exit code 3: an incomplete snapshot
Exit code 3 is the easiest to overlook. The restic backup documentation says some source files could not be read, and an incomplete snapshot was created with the remaining files.
The important word is "incomplete." Unlike a 1, a 3 does produce a snapshot. A display showing only snapshot recency could make this run look healthy. But some files from the forecast folder were not saved, and the file you need most could be one of them.
Investigate why the affected source files could not be read. The exact causes depend on your operating system and setup, so check the output for the names of skipped files. If names are missing, investigate the available diagnostics.
Treat a 3 as a real finding:
- Find which files were not read, using the output from that run.
- Fix the diagnosed cause for those files.
- Run the backup again and confirm the result is 0.
If you cannot fix the cause before the close, record the gap in writing and tell the forecast owner which files are missing from the snapshot.
Do not read size changes as pass or fail
The restic documentation notes that the transferred volume might be lower (due to deduplication) or higher than you expect. A different transfer figure does not, by itself, mean the backup failed. Compression changes the numbers too.
Use the exit code for the verdict and the size figures for trends. Compare transfer changes against known changes in the source files. A big drop with no matching change in the folder is worth investigating, but it is a question, not a failed-backup alarm.
Check your excludes before you trust the result
An exclude rule can make a backup look clean while leaving important files out. The restic documentation gives an example of an exclude that removes "files in ~/work which are larger than 1 MiB" from the backup. That kind of rule suits large caches and temporary files. It is a poor fit for a forecast folder, where a large model file may be the one you need.
Review exclude settings before each quarterly close. Ask three questions. Does any rule skip files by size? Does any rule skip files by a name pattern that could match a model or export? Was an exclude added temporarily and never removed?
Review exclusions alongside checking snapshot contents and testing restores. Record who approved each rule and why.
Keep the output you need
The restic documentation notes that if you don't pass the --verbose option, restic will print less data. That is a reasonable default for quiet jobs, but choose the output detail your investigation needs.
Store the exit code, timestamp, host name, and full run output for every backup. Use verbose output on quarter-end runs, when you most need detail. Keep logs at least as long as your restore window, so you can explain a gap later. A dated log showing a 3 on a given day answers the question "why is that version missing?" far better than memory does.
Who should own the check
A check nobody owns will be skipped the first time a close gets busy. Name a primary owner, usually someone in revenue operations or finance systems who knows the forecast folder, and a backup owner who can run the wrapper and read the logs when the primary is away.
Write ownership down next to the script. Say where logs live, where notifications go, who restores files, and who may change exclude rules. If the scheduler runs under a service account, record that too, because the account's permissions decide which files restic can read.
What to tell the forecast owner
People outside the data team want a plain answer about whether their files are safe. Translate each result into one sentence they can act on:
- After a 0: "The backup for the forecast folder completed on this date, and its snapshot includes all source files selected for backup, subject to exclusions."
- After a 1: "Check the available snapshot dates and contents while we investigate the fatal error."
- After a 3: "These named files were not saved; we will fix the cause, rerun the backup, and confirm their inclusion."
Include the snapshot date in every message. Vague reassurance does not help, and a surprise later is worse than an honest gap today.
A wrapper script you can adapt
Calling restic directly from a scheduler makes the exit code easy to lose. A small wrapper keeps the decision in one place. Adjust the paths, the notification method, and the log location for your environment.
restic backup --verbose /srv/forecasts >> /var/log/forecast-backup.log 2>&1
status=$?
case "$status" in
0)
echo "$(date -u) backup complete, all source files saved" >> /var/log/forecast-backup.log
;;
3)
echo "$(date -u) WARNING incomplete snapshot, some files unreadable" >> /var/log/forecast-backup.log
;;
*)
echo "$(date -u) FAILED with exit code $status" >> /var/log/forecast-backup.log
;;
esac
exit "$status"
Redirecting output to a file keeps a record. The --verbose flag gives the log more detail for a 3. The final exit passes the code back to the scheduler, so the job still shows failure when it should. The default branch catches exit code 1 and any other nonzero result, so an unexpected code is never treated as success.
Any code outside the three described here should be checked in the restic documentation before you decide it is harmless. Treat an unknown code as a failure until someone has checked what it means.
Test the script before the quarter closes. Run it against a test folder and force a known failure, such as a file you make unreadable, to confirm the 3 branch fires. Add notifications to the failure branches, then confirm they reach a real person and the log contains enough detail to act on.
A quarter-end checklist
Use this list in the week before a close and again after the final run.
- Confirm the scheduler runs the wrapper, not restic alone.
- Run the backup manually and confirm exit code 0.
- Review the snapshot list and confirm the newest snapshot has the expected time and paths.
- Check the most recent log for any 3, and resolve every skipped file.
- Review exclude rules for size or name patterns that could drop forecast files.
- Test one restore of a forecast file from the newest snapshot.
- Confirm the forecast owner knows which snapshot date is the most recent good copy.
Keep the checklist short enough that someone will actually finish it. Its job is to make snapshot contents, exclusions, and restore tests part of the close. Use the forecast snapshot cutoff checks when reviewing the version you intended to preserve.
Closing thoughts
Follow the result with an inspection of the files you need.
Read the code, not just the timestamp. Pair it with a restore test, a review of your excludes, and a clear owner to help identify backup gaps at quarter-end. The effort is small compared with the cost of discovering a missing forecast version during an audit.
Today, restore a forecast workbook to a scratch location and compare it with the version you intended to preserve.
Related guides: AI call scorecard checks: 5 rules before the forecast · Calendar availability: 4 tools for forecast call timing · Close date mismatches: 5 mistakes in forecast records.
Questions about backup checks
Where should a restore test put the file?
Restore it to a scratch location so you can inspect it before relying on the archive.
What should the test record contain?
Record the snapshot ID and test date so the next person can identify what was checked.