Understand model diagnostics and resolve common issues.
IOModel parses the model tolerantly: it always returns a usable tree and reports problems as diagnostics rather than failing outright. Resolving these diagnostics keeps the model correct and navigable.
Diagnostic types
| Code | Meaning |
|---|---|
invalid-yaml | A file is not valid YAML |
missing-models-yaml | The root models.yaml is missing |
invalid-slug | A model or object slug is not allowed |
duplicate-slug | Two siblings share the same slug |
unknown-reference | A link target cannot be resolved |
inline-and-file-collision | An object is defined both inline and in its own file |
unexpected-shape | A node is not the expected map/structure |
Tolerant by design
The parser collects diagnostics and continues, showing the last valid snapshot alongside a banner. You can keep working while you fix issues.
Resolving common issues
A link points to an object that does not exist. Fix the target path, or update it after a rename.
Validation routine
Check the diagnostics banner
Review reported issues with their file and line.
Fix references first
Unresolved references break navigation and workflows, so prioritize them.
Re-validate
Confirm the banner clears as you resolve each item.
Quote frontmatter and YAML values that contain colons. Unquoted colons are a
frequent source of invalid-yaml.
Last updated on