Kater checks every model when you save and compile it, and names each problem with a code. Find the code or the symptom below, then apply the fix. Many problems carry a quick fix you can apply in one step.

Where to see problems

• In Files. View › Problems opens the Problems panel.
• In VS Code. Problems show on their line as you type, with their quick fixes.
• From a terminal. kater model inspect PATH lists a file’s diagnostics without saving or running anything. kater model edit MODEL --path FILE --fix ID --write applies a quick fix.

An error blocks the save. A warning saves, and tells you about a likely mistake. Information and hints point at something worth a look.

A measure is refused

Code	What you see	Cause	Fix
measure_requires_aggregation_or_evaluation	“This measure doesn’t aggregate anything.”	A MEASURE over a raw column, a constant or a dimension.	Aggregate it, such as SUM(amount), or apply Declare as a dimension.
measure_over_window	The field “is computed over this query’s rows, so it can’t be a reusable measure.”	A MEASURE over RANK() OVER (...) or another window.	Apply Declare with CUSTOM_CALCULATION in a query, or declare a DIMENSION in a shared model.
not_additive_across	“Spend cannot be added up across Currency.”	The query adds the measure up across a dimension its rule names.	Apply the fix that groups by the dimension, or filter it to one value.
invalid_not_additive_across	The rule is refused.	It names an unknown field or a measure, or sits on a DIMENSION.	Name a dimension of this model by its field name.
unsupported_measure_context	“measures are not supported with …”	A measure passes through a SELECT with HAVING or QUALIFY, or reads two sources a join repeats.	Evaluate it with EVAL in that SELECT. Check the join’s cardinality.
dimension_outside_measure_rows	A measure cannot be grouped by a dimension.	The measure’s union branch leaves that dimension empty.	Group by a dimension both branches carry, or REMOVE it in the EVAL.

A name or field is refused

Code	What you see	Cause	Fix
field_name_in_scope	“revenue is already a measure in …”	A new field takes the name of a field the SELECT can read.	Apply Use to pass the existing field through, or Rename.
unnamed_output	Hint: the column “has no field name, so other models can’t read it.”	A computed column with only an alias.	Apply the fix that names it, or leave it if only this query uses it.
invalid_measure_rename	* RENAME is refused.	A pass-through measure keeps its name.	Declare MEASURE('new_name', EVAL(s.measure)).
custom_calculation_evaluated	EVAL is refused.	EVAL of another query’s custom calculation.	Apply Select … without EVAL.

Errors about a Kater dataset’s base columns are on Kater datasets, and errors about a table’s DDL on Database datasets.

A window or calculation is refused

Code	What you see	Cause	Fix
window_not_allowed	“A workspace root can’t run a window, because its optional filters apply first.”	A window in a workspace root or a chart.	Put it in a query, where it is a custom calculation, or in the shared model as a dimension.
custom_calculation_not_allowed	Error in a shared model.	CUSTOM_CALCULATION outside a query.	Apply the fix that declares a DIMENSION.
custom_calculation_declared_as_dimension	Warning.	A DIMENSION over a window, in a query.	Apply Declare with CUSTOM_CALCULATION.
dimension_declared_as_custom_calculation	Warning.	A CUSTOM_CALCULATION over a row value or an aggregate.	Apply Declare as a dimension, or Make it reusable with MEASURE.
invalid_window_placement	Error.	A window in WHERE, GROUP BY, HAVING or a join.	Filter it in QUALIFY, or compute it in a CTE.
invalid_aggregate_placement	Error.	An aggregate in WHERE, GROUP BY or a join, in any SELECT.	Filter it in HAVING, or compute it in a CTE.
output_column_not_grouped	Error.	An output of a SELECT with a GROUP BY reads a column that the GROUP BY holds only inside an expression, or not at all.	Write the group key that the message names in place of the column, or add the column to the GROUP BY.
column_not_grouped	Error.	A grouped SELECT reads a column outside an aggregate in HAVING, QUALIFY or ORDER BY, or in an output when it has no GROUP BY or groups by ROLLUP, CUBE or GROUPING SETS, and its GROUP BY does not hold the column.	Add the column to the GROUP BY, or read it in an aggregate, such as MAX.
sibling_not_visible_at_stage	Error.	WHERE or HAVING reads a field of the same SELECT that runs a window.	Move the condition to QUALIFY.
custom_calculation_reaggregated	Warning.	A sum or average of another query’s rank or running total.	Aggregate the field it was computed from.
excel_formula_needs_sort	“This reads another row, and the query isn’t sorted.”	An Excel formula reads another row, and the query has no ORDER BY.	Sort the query. The formula bar adds the sort when you press Enter.

A filter or parameter is refused

Code	What you see	Cause	Fix
parameterized_required_filter	“REQUIRED_FILTER … cannot contain parameters.”	A required filter reads a parameter, even one with a default.	Make it an OPTIONAL_FILTER, or write the value in.
parameter_not_allowed	“parameter … is not allowed in semantic …”	A parameter in a shared model, even an unused one, or a parameter a chart declares.	Move the filter and its parameter to the workspace root. A chart’s filter reads a parameter of its query.
chart_parameter_unknown	“The query this chart reads has no parameter …”	A chart’s filter reads a parameter that its query does not have.	Read a parameter of the chart’s query, or write the value in.
chart_parameter_not_single	“Parameter … holds more than one value.”	A chart’s filter reads a parameter that holds a list or a range.	Read a parameter that holds one value, or write the values in.
filter_not_allowed	Error.	An OPTIONAL_FILTER in a shared model.	Move it to the workspace root, or write a fixed REQUIRED_FILTER.
filter_label_directive	“a filter’s label is written in the call”	-- @label above a filter.	Write label='…' as the call’s third argument.
invalid_filter_arguments	Error.	A third argument that is not label='…'.	Use label='Region'.
conflicting_filter_metadata	Error.	Two filters with one name disagree on label or description.	Make them agree.
undeclared_parameter	Information.	The SQL reads a parameter with no entry yet.	Save or compile. Kater adds the entry.
unused_parameter_entry	Warning.	A query declares a parameter nothing reads.	Apply the fix that removes it.

Joins and metadata

Code	What you see	Cause	Fix
relationship_pruned_row_effect	“Unused relationship … was pruned; this join may …”	A join nothing reads was removed, and with it a filter or repeat of rows.	Use REQUIRED_RELATIONSHIP if the effect is intended.
possible_fan_out	“Check: SUM() over … rows while joining …”	A raw aggregate over a join that may match several rows.	Aggregate the joined side in a CTE first, or use a measure.
needs_relationship	“No unique relationship with proven exported keys is available.”	The field picker cannot find one join path to the field.	Declare the join in SQL.
ambiguous_relationship	“Several join paths apply.”	More than one relationship leads to the field.	Write the join you mean in SQL.
relationship_not_allowed	“RELATIONSHIP is not allowed in … models”	A join in a standard Kater dataset or a workspace root.	Join in a semantic model or a query.
invalid_format	The format is refused.	A format outside the list, or a currency dimension the SELECT does not hold.	Use a listed format, and select the dimension.
sql_dataset_query_required	“A SQL dataset requires one read-only query.”	A custom SQL dataset holds a script or a write.	Rewrite it as one query with CTEs.
dataset_metadata_required	“Run dataset.refresh.”	A custom SQL dataset changed outside Kater.	Run dataset.refresh, or save it again through Kater.

Numbers look wrong, with no error

Symptom	Likely cause	Fix
Totals by a joined dimension add up to more than the overall total.	Each row counts once per group it matches, such as an order shipped by two carriers.	Expected for a many-to-many grouping. Group by a dimension of the measure’s own rows for totals that add up.
A raw SUM in a scratch file or CTE is too high.	A join repeats rows. Look for possible_fan_out.	Use the model’s measure, or aggregate before the join.
A filter does not change the rows.	An optional filter applies only when switched on. A default never switches it on.	Switch it on in the filter bar, or in the run’s inputs.
A test fails, but nobody changed the model.	The data was restated upstream. The test says its SQL is unchanged.	Check the source. Accept the new numbers with kater test --update.
A money column shows no currency symbol.	The result does not return the currency dimension its format reads.	Add the currency to the query.
A field is missing from the field list.	The model above it does not project it.	Pass it through in the semantic model or the workspace root.
A model is missing from Explore.	Explore reads only Kater datasets and semantic models.	Explore the shared model the workspace reads.