When choochoo validate encounters issues, it produces specific error codes. Use this catalog to diagnose and fix problems.

Error Codes

Code	Message Template	Troubleshooting
E001	Invalid schema: {details}	Check your YAML syntax and required fields against the supported schemas.
E002	Missing required field: {field}	Add the missing field to your artifact. See Supported Schemas for required fields per schema type.
E003	Invalid file extension	Ensure files use the correct suffix for their schema type.
E004	Contract not found: {id}	The referenced contract ID does not exist. Check your project structure and ensure the file exists.
E005	Circular dependency detected	You have a dependency loop (A → B → A). Break the cycle.
E006	Quality rule failed	A quality metric is below the threshold defined in your schema.
E007	Agent boundary violation	The agent attempted an action it is not authorized to perform. Check AGENTS.md boundaries.
E008	Approval required: {policy}	This action requires human approval. See Governance (Preview).
E009	Invalid state transition	You cannot move directly between certain lifecycle states. Check allowed transitions.
E010	Version conflict	The artifact has been modified since you last read it. Pull changes and retry.

Understanding Error Context

Each error message includes the file path and line number where the issue was detected. In --json output mode, errors include structured metadata for CI/CD pipelines:

{
  "code": "E002",
  "message": "Missing required field: info.owner",
  "file": "schemas/customer-360.yaml",
  "line": 3,
  "severity": "error"
}

Use --format json with choochoo validate to get machine-readable output. The severity field can be error or warning — in --strict mode, warnings are promoted to errors.

Exit Codes

Automation scripts and CI/CD pipelines should rely on these exit codes when interpreting CLI results:

Code	Name	Description
0	SUCCESS	Command completed successfully.
1	VALIDATION_ERROR	Schema validation failed or quality rules were not met. See error codes above.
2	CONFIG_ERROR	The choochoo.toml file is missing or invalid.
3	NETWORK_ERROR	Failed to communicate with the remote API or registry.
4	AUTH_ERROR	Authentication failed or insufficient permissions.
5	NOT_FOUND	The requested artifact or resource does not exist.
10	APPROVAL_REQUIRED	The action requires human approval and cannot proceed automatically.
11	APPROVAL_REJECTED	The action was rejected by an approver.
99	INTERNAL_ERROR	An unexpected bug in the CLI. Please report via Contributing.

Usage in CI/CD

choochoo validate --strict
EXIT_CODE=$?

case $EXIT_CODE in
  0)  echo "All validations passed" ;;
  1)  echo "Validation failed — check error messages" ;;
  10) echo "Human approval required — notifying approvers" ;;
  *)  echo "Unexpected exit code: $EXIT_CODE" ;;
esac

The --strict flag treats warnings as errors (exit code 1). Configure this as the default in Configuration.

Related

• CLI Reference — Full command documentation including output format options.
• Configuration — Configure strict mode and schema versions.
• CI/CD Integration — Set up automated validation checks.