Skip to content

Error Handling

Dataface currently exposes a few distinct classes of errors, and they do not all behave the same way.

Current Behavior

  • Parse errors stop before compilation finishes.
  • Validation errors stop before rendering starts.
  • Query execution failures currently fail the whole render response in the playground.
  • Chart data-shape errors can render inline per chart when the query succeeds but the chart contract is invalid.

That last category is the closest thing to partial rendering today. For example, a KPI that receives multiple rows can render an inline chart error while neighboring charts still render successfully.

Local Playground Error Examples

The playground now includes a local-only errors category under:

examples/playground/faces/errors/

Those examples are intentionally hidden unless the playground is served from localhost, 127.0.0.1, or ::1, so shared dev and production environments do not show internal debugging fixtures. That gate only affects the gallery listing. Direct example and thumbnail URLs still work so docs, tests, and debugging links can point to a specific fixture when needed.

Available examples:

  • parse-error.yml - early YAML shape failure (YAML must be a mapping) that exercises the same pre-render error surface without committing syntactically invalid YAML into the repo
  • missing-query.yml - chart references a query that does not exist
  • validation-extra-field.yml - schema validation rejects an extra field
  • execution-missing-file.yml - query execution fails because the CSV file is missing
  • partial-chart-error.yml - one chart renders an inline ChartDataError while the rest of the board still renders
  • multiple-chart-errors.yml - multiple KPI charts render inline chart errors from the same multi-row dataset

Choosing The Right Example

Use these examples to answer different UI questions:

  • Use parse or validation examples when you are testing editor feedback and compile-time error presentation.
  • Use execution examples when you are testing how the playground surfaces runtime failures that abort the render.
  • Use the partial chart examples when you want to inspect the inline chart-error treatment without losing the whole board.

What Is Not Implemented Yet

The broader error-handling initiative still describes additional behavior that is not present in the current playground:

  • Query-level partial rendering where one failed query out of several still leaves the rest of the board intact
  • Structured streaming progress and verbosity controls across CLI, MCP, and playground surfaces
  • A larger, policy-driven error-handling model shared across all consumers

Those future requirements are tracked in:

  • tasks/workstreams/dft-core/initiatives/m2-error-handling-streaming-and-progressive-rendering/index.md
  • tasks/workstreams/dft-core/initiatives/m2-error-handling-streaming-and-progressive-rendering/spec.md

If you specifically want to test a raw YAML syntax error such as a missing bracket or colon, paste that broken YAML directly into the playground editor. The committed fixture corpus cannot contain syntactically invalid YAML because the repository enforces YAML validation in pre-commit.