Learn

Diagnose Validation and Trace Output

Use validation errors and trace output to find schema mismatches, missing fields, and render-time problems in a Cuddler workflow.

Tutorial path

A practical debugging order

The goal is to classify the failure quickly and then inspect the smallest boundary that explains it.

1Read code, message, and path

Start with the exact failure signal instead of broad speculation.

2Classify the boundary

Decide whether the issue belongs to data validation, template validation, or rendering.

3Check version alignment

Make sure the workflow is not failing because the wrong family is in play.

4Use trace to locate traversal

See where the workflow stopped matching the expected structure.

5Fix the smallest contract

Update the narrowest boundary that fully explains the failure.

Trace output is for locating the mismatch, not replacing schema review.

When something fails, start with the error path and the schema boundary. That keeps the debugging process focused and prevents you from trying to fix rendering when the real problem is still in the input contract.

A practical order of operations

  1. Read the error code, message, and path first.
  2. Decide whether the failure belongs to data validation, template validation, or rendering.
  3. Check the schema identity and version alignment.
  4. Use trace output to confirm where traversal stopped.
  5. Fix the smallest contract that explains the failure.

What trace output is for

Trace output should help you answer a simple question: where did the workflow stop matching the expected structure? It is useful for path-level debugging, but it should not replace the actual schema review.

Common failure patterns

  • A required field is missing in the data.
  • A schema path points to the wrong version.
  • A template references a field that is not present.
  • Render-time sanitization strips content that should not have been trusted.