● zegit · proves
Error codes
The ZG_ERR_* codes are a stable public contract — the gateway and CLI return them, and tooling parses them. Each comes with a structured payload and a remediation.
Reference
| Code | Cause | Remediation |
|---|---|---|
ZG_ERR_AOV_MISSING | No AoV ref for the commit. | Run zg validate, push again with the AoV ref. |
ZG_ERR_AOV_MISSING_TREE | AoV subject lacks a tree SHA (no replay binding). | Re-run zg validate with an up-to-date zg. |
ZG_ERR_AOV_SIGNATURE_INVALID | AoV signature doesn't verify against the signer cert. | Re-run validation; the cert may be compromised/misconfigured. |
ZG_ERR_CERT_EXPIRED | Signing cert expired. | Run zg auth login. |
ZG_ERR_CERT_REVOKED | Signing cert revoked by the CP. | Check the audit log; re-enroll or contact a security admin. |
ZG_ERR_POLICY_MISMATCH | AoV policy digest ≠ the current required policy. | Re-run zg validate under the current policy. |
ZG_ERR_REQUIRED_CHECK_MISSING | AoV is missing required checks from the ZEGITFILE. | Run zg validate so all required checks pass. |
ZG_ERR_SIGNER_UNAUTHORIZED | Signer not authorized for this repo. | Verify roles in the ZEGITFILE. |
ZG_ERR_CRITICAL_AREA_UNAPPROVED | A critical-area change is missing required approval. | Create a TR / obtain maintainer approval. |
ZG_ERR_EVIDENCE_STALE | AoV git state ≠ the pushed commit/tree. | Re-run zg validate against the current commit. |
ZG_ERR_POLICY_BLOCK | Risk policy forbids autonomous delivery. | Obtain approvals / create a TR. |
ZG_ERR_TASK_CONTRACT_INVALID | A required task contract is absent or invalid. | Create/fix the contract, then re-validate. |
ZG_ERR_KEY_MISSING | A signing key is required but not provided/loadable. | Run zg evidence keygen; pass --key. |
ZG_ERR_NOT_INITIALIZED | .zegit/config.yaml is missing. | Run zg init. |
ZG_ERR_BUNDLE_TAMPERED | A bundle file mismatches the signed manifest hash. | Re-download from a trusted source and re-verify. |
ZG_ERR_SIGNATURE_INVALID | A DSSE signature doesn't verify against the key. | Re-sign with zg evidence sign, or use the correct --key. |
ZG_ERR_QUORUM_NOT_MET | A TR lacks the required valid approvals. | Get authorized approvals, then zg tr finalize. |
ZG_ERR_REVOCATION_LIST_STALE | The gateway's cached revocation list is older than max staleness (60s). | Restore CP reachability; the push succeeds after a refresh. |
Process exit codes
Distinct from the string codes above, the CLI uses numeric exit codes so CI can branch on them:
| Exit | Meaning | Where |
|---|---|---|
0 | Success / ALLOW | all commands |
10 | REQUIRE_REVIEW | zg validate, zg evidence |
20 | BLOCK / signature invalid / bundle tampered | zg validate, zg evidence |
30 | Quorum not met | zg tr finalize |
1 / 2 | IO/runtime error / usage error | all commands |
Branch on the exit code, not on log text. A clean 0/10/20 split maps directly onto ALLOW / REQUIRE_REVIEW / BLOCK.
Authoritative reference, generated from the component repos. Spot something stale? Tell us.