Execution and Validation Errors

This page lists common errors you can get while building definitions, running previews, and exporting reports.

Error shape

Validation errors are returned as path/message pairs.

{
  "errors": [
    {
      "path": "selected_columns.0.field_key",
      "message": "Selected field is not exposed by source."
    }
  ]
}

Common validation errors

Path example	Meaning
source_key	Unknown source key
selected_columns	No selected columns were provided
selected_columns.N.field_key	Column is unknown or not selectable
sorts.N.field_key	Sort field is unknown or not sortable
filters.children.N.field_key	Filter field is unknown or not filterable
filters.children.N.value	Invalid value shape for operator

Operator-specific value errors

• between and not_between require exactly two values.
• in and not_in require an array value.
• last_n_days requires a positive integer value.
• is_null, is_not_null, this_week, this_month, and this_year do not require a value.

Sort errors

• Sort direction must be asc or desc.
• Sorting by non-sortable fields fails validation.
• Sorting by relation fields is not supported by the current compiler.

Export errors

• Export fails if no exporter is registered for the requested format.
• Use only supported formats like csv and xlsx unless you register custom exporters.

Handling guidance

• Map errors by path first, then show user-friendly messages.
• Do not depend on exact message text for control flow.
• Keep engine errors internal and map them to stable app-level error codes in your UI/API layer.