Error Messages
Catalog of common error codes
When choochoo validate encounters issues, it produces specific error codes. Use this catalog to diagnose and fix problems. For the corresponding process exit codes, see Exit Codes.
| Code | Message Template | Troubleshooting |
|---|---|---|
| E001 | Invalid schema: {details} | Check your YAML syntax and required fields against the schema definitions. |
| E002 | Missing required field: {field} | Add the missing field to your artifact. See Products, Contracts, or Workflows for required fields. |
| E003 | Invalid file extension | Ensure files use the correct suffix (e.g., .contract.yaml). See File Structure for naming conventions. |
| E004 | Contract not found: {id} | The referenced contract ID does not exist in contracts/. Check your project structure and ensure the contract file exists. |
| E005 | Circular dependency detected | You have a dependency loop (A → B → A). Break the cycle. Use choochoo lineage show to visualize the dependency graph. |
| E006 | Quality rule failed | A quality metric (e.g., freshness) is below the threshold defined in your contract. See Validation Rules for the quality rule grammar. |
| E007 | Agent boundary violation | The agent attempted an action it is not authorized to perform. Check the agent's boundaries in agents/AGENTS.md and its System Card. |
| E008 | Approval required: {policy} | This action cannot proceed until approved by a human. See Approval Workflows to understand the policy that was triggered, and Risk Scoring for the threshold that caused it. |
| E009 | Invalid state transition | You cannot move directly between certain lifecycle states (e.g., draft → active). Check the state machine for allowed transitions. |
| E010 | Version conflict | The artifact has been modified since you last read it. Pull changes and retry. See Version Compatibility for supported spec versions. |
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 that can be parsed by CI/CD pipelines:
{
"code": "E002",
"message": "Missing required field: info.owner",
"file": "products/customer-360.yaml",
"line": 3,
"severity": "error"
}Use --format json with the choochoo validate command to get machine-readable output. The severity field can be error or warning — in --strict mode, warnings are promoted to errors. See Configuration to set strict mode as the default.
Related
Exit Codes
Map process exit codes to error categories for CI/CD automation.
CLI Reference
Full command documentation including output format options.
Validation Rules
Understand the validation pipeline and quality rule grammar.
Configuration
Configure strict mode, schema versions, and governance policies in .choochoorc.