Classify restic job failures from the documented exit status

Bottom line: DSE recommendation: decide how a scheduled backup job will report an unsuccessful or unrecognized result before using its run history as operational evidence. Keep that decision separate from which files were selected and whether a recovery exercise has passed.

Source fact: what the authority says

The restic scripting guide identifies version 0.19.1. Its general table defines zero as success. For backup, code 3 means some source data could not be read; for forget, it means one or more snapshots could not be removed. Unknown exit codes must be treated as failure, with command-specific help providing further detail.

What the source does not establish

This table is not proof that a particular job protected the intended files, produced an application-consistent recovery point or can restore a service. This article does not certify a wrapper, scheduler or installed client. Treat those as separate review subjects and retain uncertainty when the observed result cannot be explained.

Applicability questions

• Which client version and exact command will the job execute, and who owns changes to that combination?
• Does the wrapper preserve the process result before running another command, and what will its attended recipient call non-success?
• Where will an unexpected code, interrupted run or missing completion record be investigated?
• Which separate evidence will establish backup scope and recoverability rather than merely process completion?

DSE recommendation: controlled next steps

The following paragraphs are DSE recommendations, not instructions or guarantees from the source.

Build the classification around the exact operation, not a green status shared by all jobs. In the review sheet, give the backup and forget cases their own names, command identifiers and reviewed source meanings. Keep the recorded exit status next to the operation so the interpretation can be checked.

Ask the reviewer to explain two status-3 records without relying on a generic label. Which one reports unreadable source data, and which one reports unsuccessful snapshot removal? Require that distinction to survive the scheduler, dashboard and notification handoffs. Keep secrets and sensitive file names out of the shared comparison.

Give an unknown result a separate non-success route with a named investigator. Preserve the native status and redacted diagnostics before other wrapper steps. Decide retry or recovery policy separately; neither is established by this general code table. Keep a missing run distinct from a completed run with an unsuccessful result.

Verification and evidence

Proposed verification, not a performed test: define BACKUP-READ for a genuine backup status 3 and FORGET-REMOVE for a genuine forget status 3. Obtain either result only in a disposable, nonsensitive exercise where the condition can be safely reproduced; otherwise mark it untested. Compare each with its command-specific meaning above, without asserting that a snapshot was created.

Define UNKNOWN-RESULT as a synthetic status absent from the reviewed table, injected at the wrapper boundary. Require its downstream record to remain non-success and identify the injection clearly. Retain the invocation, native or injected value, classification and attended notification. Ask another operator to trace all three records through each handoff; assess backup scope and restoration evidence separately.

Official references

• restic 0.19.1 — Scripting — official product documentation; source version and applicability limits are stated above.

Source review completed October 28, 2026. Recheck the official documentation and deployment-specific applicability before a production change.