Errors and exit codes

vops errors are part of its public automation contract. JSON output separates a stable code from the human message, affected path, retryability and suggested action.

Exit codes

Exit	Meaning
0	The command completed successfully.
1	The operation ran and failed.
2	Invalid input, flag, argument or identifier.
3	Validation or stale-plan failure.
4	A prerequisite is missing.
5	Explicit approval is required.
6	The installed build does not implement the capability.
7	Credentials are missing, invalid or too narrow.
8	Partial success; inspect the result before continuing.

Use the structured error code for branching; use the message and suggested action for a person.

Error families

Prefix	Area
VOPS_SPEC_*	flui.yaml parsing, schema, fields and generation.
VOPS_GITHUB_* / VOPS_BUILD_*	Repository discovery, GitHub access and CI builds.
VOPS_PLAN_* / VOPS_APPROVAL_*	Missing, stale or unapproved plans.
VOPS_CATALOG_*	Catalog lookups.
VOPS_HOST_* / VOPS_SERVER_* / VOPS_APP_*	Inventory and target resolution.
VOPS_CREDENTIALS_*	Missing or unavailable credentials.
VOPS_RELAY_*	Opt-in watch relay connection.
VOPS_OPERATION_*	Execution failures that do not have a more specific family.

Codes are additive. Scripts should not infer behavior by parsing an English message.

Approval is not an error to retry blindly

VOPS_APPROVAL_REQUIRED means the operation stopped before the guarded effect. Show the plan to a person and make an explicit decision. Repeating the same command without approval should produce the same result.

A stale plan is a useful refusal

VOPS_PLAN_STALE means the current manifest, target or relevant input no longer matches the approved plan. Create and review a new plan. Do not edit the stored plan ID or force the old approval onto new inputs.

Reporting a failure safely

Prefer:

vops <topic> <command> ... --json > vops-result.json

Review the file for deliberately revealed values before sharing it. Provider tokens, private keys and normal secret inputs should already be redacted; an explicit credentials reveal command is a different contract.