downpipe exit codes and verification outcomes

The downpipe reader commands finish with a process exit code that says what was proven. This page is the normative contract for those codes, for a break-glass recoverer or a drill script that must react to a verdict, not prose.

The codes are stable and machine-readable, so a script can branch on them with confidence. A clean run exits zero; every non-zero code names one specific failure class, and the tool also prints a human-readable verdict to stderr alongside it. The two reading-and-checking commands that carry this contract are verify and restore; the command reference for both is the CLI command reference. verify-report returns three of the same codes about a signed report rather than an archive: see the verify-report codes.

The normative reader exit codes

These six codes are the SPEC-normative reader set. The reader maps an internal exit error to its process exit status, so the code you observe is the verdict the verification produced.

The checks behind code 0 run read-only on verify and run again, value by value, on a restore --apply, so a restore that writes also re-proves the run as it goes and a per-record mismatch surfaces as code 4 rather than a silent partial write.

Code 1, the uncoded fallback

Code 1 sits outside the six-code SPEC-normative set, the same way 7 to 14 do, but for the opposite reason: it is not a classified verdict at all, it is what the reader returns when nothing else applies. A restore --apply that writes some records but hits at least one per-record failure still exits its highest normative per-record code (4 for a plaintext-hash mismatch, 2 for a structural or AEAD failure); 1 is reserved for the case where every failed record’s cause was itself uncoded, for example a write the restore target refused. Unlike the hard-failure codes 2 to 6, code 1 is worth a retry once the underlying problem is fixed rather than an escalation. A destination that could not be reached at all (a network or DNS failure, a refused connection, or a non-2xx status before any bytes arrived) is a distinct case with its own code: see code 11 below.

Code 11, the destination-unreachable code

Code 11 sits outside the six-code SPEC-normative set, the same way 7 to 10 and 12 to 14 do. It marks a read that retrieved no bytes at all, which code 2 does not cover. Code 2 means bytes were retrieved then failed a hash, signature or authenticated-decrypt check, a real reason to stop and treat the archive as suspect. Code 11 means the request never got bytes back at all, most often a wrong --s3-endpoint or --s3-bucket (or --azure-endpoint or --azure-container), or an expired AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or AZURE_STORAGE_KEY / AZURE_STORAGE_SAS_TOKEN), worth a retry once fixed rather than an escalation. The two codes ask for opposite responses: retry once the endpoint or credentials are fixed, or stop because the archive may be compromised.

A truncated or oversized read stays on the 2 side, not 11: some bytes did arrive, so something is now known about them (an AEAD tag or a signed hash to check them against), and a partial or oversized object is at least as consistent with tampering or corruption as with a network blip. A read failure the reader cannot positively attribute to the destination keeps the code its read site assigns, most often 2: the deliberately safer default, since an unclassifiable failure reads as a possible tamper finding, never as a silent invitation to retry.

From reader 0.3.4, when a pass reads every segment (verify --deep, or an applied restore) and the run itself already has a code from 2 to 6, a segment read that fails this way does not replace that code. A signature failure with an unreachable segment exits 2, not 11.

Code 11 is reachable over either network backend, --s3-endpoint and --azure-endpoint. verify, attest, restore, inspect, keys and prune all honour it on the same boundary, and between the two backends that covers all four destinations: R2, an S3-compatible store and Google Cloud Storage over --s3-endpoint, and Azure Blob Storage over --azure-endpoint (see destination providers compared). On Azure the two you are most likely to meet arrive named rather than as a bare status: a wrong, absent or expired credential answers 403 AuthenticationFailed, and a container that is not there answers 404 ContainerNotFound. A local --archive read failure is never reclassified to 11: a local “no such file” or “permission denied” carries far less signal than a network 403 or 404 about whether an object is merely inaccessible or genuinely gone, so it keeps the code its read site assigns, most often 2 (see also the pruned-run wording in the CLI command reference for prune, which reasons through the same ambiguity for a locally absent run tree).

The provisioner code, outside the normative set

preflight is on the provisioner path, not the reader path, so it deliberately uses a code outside the normative reader set rather than reusing one.

preflight keeps 7 distinct from 2 on purpose: a deploy-time account check failing is a different thing from a reader’s signature or recompute verdict, and exit-status-driven tooling can tell them apart. A check the token cannot read shows as unknown and still exits 7, because a check that could not run is not a pass. An invalid token aborts loudly, and a plain usage error from preflight is still the normative 6.

The three restore advisories, also outside the normative set

restore --apply can return three further codes that sit outside the six normative reader codes and outside preflight’s 7. verify --deep can return one of them, 8. A fourth, 9, is returned by any command that accepts custody artefacts and is not an advisory at all.

Code 8 is deliberately kept apart from the hard-failure codes 2 to 6 and from 7: the records genuinely verified or restored, so the run should never be read as a clean, complete result nor as a failure. A hard verification or per-record failure always takes precedence over this advisory: the reader only returns 8 once every check that could produce 2 to 6 has already passed.

Code 9 is not in that family at all. It is a hard failure, like 2 to 6, but of the custody artefacts rather than of the archive: no key was recovered, so nothing was read. Its number sits between two advisories, but it is not one of them.

Code 10 is kept apart for the same reason and is separate from 8 because the gap is different in kind: an incompleteness marker is a record that landed carrying a placeholder, while an unwritten record did not land at all. Where a restore would qualify for both, 10 is returned, since the absent record is the larger gap. What 10 must never be is 0. A summary line on stderr is not something a recovery script reads, so a restore that skipped records reports it in the exit status rather than letting automation conclude a clean full restore.

Code 12 is the mildest of the three, and the numbers are not a ranking, so read them by what they say rather than by size. Code 10 says records are in the archive and not on your disk. Code 8 says records landed carrying a placeholder instead of the source’s data. Code 12 says every byte landed intact and this release of the reader cannot render one of them, which another release can. Both of the others take precedence over it, and any hard verification or per-record failure takes precedence over all three.

Code 12 is 12 rather than a reuse of 8 because the two point in opposite directions. An incompleteness marker is a statement about the data, that the source was only partly available when the backup ran. Code 12 says nothing about the data at all, only about this reader. A script that treated them alike would either chase a backup-time gap that never happened or apply a file it must not apply. An archive written by a newer engine can open, verify and restore through a reader that cannot render its D1 bodies, because the body-format label is versioned independently of the archive. Code 12 tells you this before sqlite3 does.

Code 13, the dangling-segment code

Code 13 separates an absent segment from a failed authentication tag, which exits 2, and the two print different verdict lines.

The two remedies are opposite. An absent segment means fetch the object from another copy. A failed tag means the bytes were altered and this copy must not be trusted. Being told your data is corrupt when it is merely absent points you away from the replica that would have restored you, which is the more damaging of the two mistakes.

The receipt draws the same line: danglingSegments reads 1 against an absent segment and 0 against a flipped byte, and the exit status and the printed verdict line agree with it.

Precedence, because the numbers are not a ranking. Any per-record failure that did fail a check wins: a run with one absent segment and one failed tag exits 2, or 4 for a plaintext mismatch, never 13. A signature or structural verdict on the run itself wins too. Against the three advisories 13 wins, because 8, 10 and 12 all describe records that are in the archive and this describes records that are not.

Code 13 is not a reuse of 3, and not a reuse of 11. Code 3 is the structural count check, raised before a single segment is fetched, and it says the manifests do not add up; 13 says the manifests add up exactly and the bucket is missing an object they name, which is a finding about the destination rather than about the manifest. Code 11 means the destination refused the request or could not be reached before any bytes arrived, so nothing at all is known and a retry against the same place may work; with 13 the read was answered.

Code 14, the incomplete-prune code

Code 14 exists so an automated caller does not read a prune that removed nothing as a success. Reader 0.3.3 exits 0 for a fully refused prune --apply. The code applies to --apply only: a dry run plans and deletes nothing, so it has nothing to leave undone.

Running downpipe with no command at all prints usage and returns 6, the same as any other usage error: a bad flag, an unparseable run id, a missing source, or a missing or unreadable identity, signer or receipt-signer key file. Code 2 is a verdict about an archive, or about a report for verify-report. A run given no command has opened nothing to have a verdict about. A partial restore is never presented as a success: see code 1 above for how an uncoded per-record failure is the one case that falls back to a flat 1 rather than surfacing its true class.

The verify-report codes

From reader 0.3.4, verify-report checks the signature on an assurance report the engine generated, against your signer.pub. It returns 0, 2 or 6, and each code is a statement about the report file you gave it, not about an archive. The numbers keep their meaning from the normative table above. Code 2 is a check that ran and failed, and code 6 is input the command could not check.

A code 0 covers only the JSON you passed. Each request to the engine generates a new report, so a PDF and a JSON fetched after it are two separate reports, and verifying the JSON says nothing about the PDF. Code 0 also does not check the report’s figures against your account again: it shows who signed them and that they did not change. For the report kinds and the auditor’s procedure, read signed reports.

The salvage overrides

Three flags let a recoverer proceed past a failing verdict on purpose. They are narrow by design, never widen each other, and the receipt always records the outcome: an overridden run is never presented as clean. Two of them acknowledge different halves of exit 5, so read the stderr line before you choose: it names the acknowledgement that fits what the reader found, and the other one will refuse the command a second time.

--allow-stale acknowledges a run’s age, and only its age

--allow-stale is the acknowledgement for a run the RUNLOG reports as old. It applies when the RUNLOG verified against your --signer, is internally consistent, and says either that this run is not the latest for its downpipe or that its maximum index is below your --min-runlog-index pin. Restoring a superseded run on purpose, for a point-in-time recovery, is exactly what it is for.

It does not waive the RUNLOG’s signature, presence or self-consistency. So it covers two of the four causes listed for code 5 above, not all four: if the reader could not check freshness at all, or checked it and found the log contradicts itself, --allow-stale refuses the command again and the stderr line says so. It also overrides nothing outside code 5: it does not suppress a signature, integrity, completeness or plaintext failure, so a run that is both stale and tampered still fails on the tamper verdict, leaving codes 2, 3 and 4 untouched.

--allow-unverified-runlog acknowledges an untrustworthy RUNLOG

--allow-unverified-runlog is the acknowledgement for the other half of code 5, where the problem is the RUNLOG itself rather than the run’s age. It covers a RUNLOG that is absent, unreadable, unparseable or empty, one that does not carry this run, one that fails to verify against your --signer or disagrees with the signed root manifest, and one that verified and is internally contradictory, such as a duplicated index or a forked chain.

It is a stronger acknowledgement than --allow-stale, and a deliberately uncomfortable one, because nothing is then established about this run’s recency: a bucket someone has rolled back or replaced looks exactly like this. Before you use it, fetch the RUNLOG and its detached signature from a trusted copy and re-run, or compare your log against one you trust. Reach for it only when you have satisfied yourself the archive is the one you meant to read.

--allow-unverified is the last-resort salvage path

--allow-unverified overrides a signature or recovery-bundle failure to still return the physically present, authenticated bytes when a verification key is missing or a signature fails. This keeps a key-management slip from becoming total data loss, but it is not verified restore: the bytes are decrypted and authenticated by the envelope, yet the run is not proven whole or genuine. Treat it as a salvage path, never as a routine restore. When you use it, the receipt records the mode allow-unverified and the signature result.

--allow-unverified implies both of the freshness acknowledgements above, so it also clears code 5 in either of its halves. An operator who will proceed on an unsigned root manifest is not being protected by a separate question about the RUNLOG. The narrower flags exist so that acknowledging an old run does not silently also accept an unverifiable one.

The recovery-bundle binding

--check-bundle is an opt-in extra check that binds the in-bucket recovery documents (the versioned FORMAT.md pointer and RECOVER.md) to their signed SHA384SUMS, so a recoverer who relies on the bundled instructions can confirm the instructions were not altered. A bundle-check failure is fatal: it produces exit 2 unless --allow-unverified downgrades it to a warning. Trusting altered recovery instructions is the failure the binding exists to catch.

What the receipt records

A signed, machine-readable receipt records the same outcome in detail. Write one with --receipt <path> (a path of - writes it to stderr so stdout stays clean for a data sink), and sign it with --receipt-signer <file> if you hold the session signer private key. The receipt carries the exit code, the signature and completeness verdicts, the recovery-bundle result, and a valueVerified flag. From reader 0.3.4, when records fail, the receipt’s exit code is the code the process exits with, for restore and for verify --deep. This code can be the uncoded 1, for example when the restore target could not write a record. The receipt does not record the advisory codes 8, 10 and 12.

valueVerified is true only when the offline binary actually hash-checked the written value against the signed manifest. That is the case for the file, env and discard sinks on a real --apply, where each value is decrypted and its plaintext hash is checked as it is handled (the discard sink verifies the value and then writes nothing). It is false for a dry run, which handles no value, and false for a verify without --deep, which reads no value at all. A verify --deep sets it true only when every record decrypted and hash-checked. So valueVerified: true on a discard receipt means every record was decrypted and verified even though nothing was written.

Where this fits

For every command and flag that produces these codes, read the CLI command reference, which also owns the deep offline-recovery walkthrough. For the engine-side and in-console restore that the portal drives rather than this binary, read the restore flow. For why a genuine drill uses the break-glass identity and keeps the receipt, read prove recoverability. For the freshness and anti-rollback model the code 5 verdict comes from, read the threat model.

Last updated 25 September 2026.