● 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_ACTOR_MISMATCH | The AoV's actor is not the identity its signer certificate names. Observe-only by default: the gateway accepts with a NOTE unless the operator sets ZEGIT_REFUSE_AOV_ACTOR_MISMATCH=1. | Upgrade zg on the host that ran zg validate, re-validate and push the new AoV. |
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_INIT_INCOMPLETE | zg init could not complete a step (config, ZEGITFILE, gateway wiring or the pre-push hook). | Fix the named cause and run zg init again, or add the printed hook block by hand. |
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_BUNDLE_CLAIM_UNPROVEN | A claim in the bundle's signed manifest (quorum, AoV coverage, policy digest) is not what the bundled evidence proves when recomputed offline. | Do not trust the summary; regenerate with zg evidence bundle and verify again. |
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_IMAGE_ALREADY_SIGNED | The Control Plane was asked to sign a different image digest (or payload) under a release tag and image name it already signed. | Deploy the recorded digest, or cut a new version through the Tag Request ceremony. |
ZG_ERR_DEPLOY_CONFIG_ALREADY_SIGNED | A second, different deploy-config digest was submitted for a commit whose deploy config is already signed. | Publish the recorded digest, or push a new commit to the default branch. |
ZG_ERR_DEPLOY_CONFIG_COMMIT_NOT_ACCEPTED | A deploy-config signature was requested for a commit not shown as accepted on the repository's default branch. | Sign the artifact of a default-branch commit, from the workflow its push triggered. |
ZG_ERR_SIGNING_TOKEN_UNBOUND | A signer token that names no repository was presented for image or deploy-config signing. | Issue a token bound to the repository, store it as the CI secret, revoke the old one. |
ZG_ERR_SIGNING_REFERENCE_OUTSIDE_REPOSITORY | The signing payload names an image or manifests repository outside the repository the token is bound to. | Sign a reference under the repository's own image path, or have an owner correct its image_path_prefix. |
ZG_ERR_SIGNING_WINDOW_CLOSED | An image signature was requested more than 6 hours after the gateway accepted the tag (or before), or a deploy-config signature more than 1 hour after the commit reached the default branch. | Cut a new release tag, or push a new default-branch commit; a late re-run cannot be signed. |
ZG_ERR_REPO_SIGNING_KEY_UNAVAILABLE | The repository signs with its own keys and the Control Plane can neither use nor generate that key. | Configure ZEGIT_REPO_SIGNING_WRAP_KEY (or the previous wrap key) and retry. |
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. |
ZG_ERR_DUPLICATE_REF | The gateway refused a push whose commands name the same ref more than once. | Push each ref once; a client never sends a ref twice by itself, so report a push that does. |
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.