Troubleshooting
Find the responsible layer, inspect the exact path and version, and fix a Cuddler failure without debugging the entire pipeline.
Section mapTroubleshooting at a glance
These pages are designed to be used together. Read across the map to see the main topics this section covers.
How to read and resolve validation errors when Cuddler rejects data or template input.
Open Validation ErrorsHow to diagnose failures that appear after validation passes but rendering still fails.
Open Render FailuresHow to resolve problems caused by mixing the wrong schema, page, or artifact version.
Open Version MismatchHow to diagnose markdown-template structures that do not validate or do not render as expected.
Open Template Structure IssuesWhen the workflow stops, the error should narrow the investigation rather than expand it. Start with the responsible layer, preserve the failing input, and change the smallest contract mismatch first.
When Cuddler does not behave as expected, the fastest fix usually starts with the contract:
- validate the data against the correct schema
- validate the template document separately
- confirm the versioned routes and schema identities match
- check the exact template structure, table widths, and reference definitions that failed
Common Problems
What To Check First
- Confirm that the data and template document are both using the intended schema version.
- Confirm that the instance
"$schema"value matches the canonical schema"$id". - Confirm that the failure is not a sanitization or asset-loading issue.
- Confirm the reported path and compare it to the actual document shape.
If the problem still is not obvious, open the specific troubleshooting page that matches the symptom and work through the checks in order.
