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 and other runtime chart errors render as inline callout cards (
tone: negative) while neighboring charts still render. - Chart data-shape errors use the same inline callout treatment when the query succeeds but the chart contract is invalid.
For example, a KPI that receives multiple rows renders an inline negative callout while neighboring charts still render successfully. Bad SQL on one chart behaves the same way when other charts on the face succeed.
When a face has only one chart and that chart fails at runtime, the inline callout fills the tile — it can look like a full-page error even though the render response succeeded with chart_errors populated.
Structured Compile Errors¶
Compile-time failures surface as a list of typed StructuredError objects.
Each StructuredError carries:
| Field | Description |
|---|---|
code |
Machine-readable error code (e.g. DF-COMPILE-EXTRA-FIELD) |
message |
Human-readable description |
line |
1-indexed source line where the error originates, when available |
field_path |
Dot-separated path to the offending field (e.g. style.charts.bogus_field) |
hint |
Optional fix suggestion |
doc_url |
Link to documentation for this error |
Playground¶
The playground renders one card per error — code badge + message + optional line pointer — instead of collapsing all errors into a single block.
VS Code¶
The language server runs compile diagnostics on save (in addition to fast schema checks on every keystroke). Each StructuredError maps to a VS Code squiggle at the correct source line.
CLI¶
dft validate and dft render print each StructuredError as a Rich panel.
What Is Not Implemented Yet¶
Planned behavior not yet implemented:
- Structured streaming progress and verbosity controls across CLI, MCP, and playground surfaces
- A larger, policy-driven error-handling model shared across all consumers
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.