● 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_MISSING_POLICY_DIGEST | AoV records no policy_ref.digest. | Re-run zg validate with an up-to-date zg. |
ZG_ERR_AOV_SCOPE_MISMATCH | The active policy pins a validation scope and the AoV did not run the sanctioned pipeline. | Restore the pinned .zegit/config.yaml, or zg policy scope → propose → owner approval; re-validate. |
ZG_ERR_AOV_STEP_MISSING | A required_steps entry is not required-and-passed in the AoV. | Restore the step with required: true and re-validate, or propose a policy without it. |
ZG_ERR_AOV_ORG_MISMATCH | The signer leaf is scoped to another organization. | zg auth login --org <org> for the repository's organization and re-validate. |
ZG_ERR_AOV_SIGNER_ROLE | The signing cert carries a role with no code authority (e.g. provisioner). | Validate and push as a developer / maintainer / owner identity. |
ZG_ERR_AOV_PRODUCER_DIRTY | The AoV on master/main or a tag was produced by a zg built from a dirty tree. | Re-validate with a released zg (zg update). |
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, is missing, or is unexpected. | Re-download from a trusted source and re-verify. |
ZG_ERR_EVIDENCE_INCOMPLETE | zg evidence bundle found commits in the range with no valid AoV. | zg validate each listed commit and re-bundle; --allow-incomplete accepts the gap knowingly. |
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_ARTIFACT_ALREADY_SIGNED | The Control Plane was asked to sign a different checksums file for a release version it already signed. | Cut a new version through the Tag Request ceremony; release material is immutable once signed. |
ZG_ERR_HSM_MESSAGE_TOO_LARGE | A hardware-resident Ed25519 key was asked to sign more than the device bound. | Keep the payload within the bound, or move that purpose to an ECDSA P-256 key. |
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 / bundle incomplete / no AoV for commit | zg validate, zg evidence, zg aov inspect |
30 | Quorum not met | zg tr finalize, zg policy activate |
31 | Watch window closed with quorum still unmet | zg tr watch |
4 – 7 | Diverged / pending / not advanced / tip has no AoV | zg push, zg verify-forward |
1 / 2 | IO/runtime error / usage error | all commands |
The gateway's pre-receive hook itself exits 0 when every ref is accepted, 1 when at least one ref is rejected, and 2 on a configuration error. Two gateway-side codes are not ZG_ERR_* catalog entries: CP_QUORUM_UNVERIFIED (no quorum verify key) and POLICY_NOT_ACTIVE (no activated release policy) — see Gateway troubleshooting.
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.