# Error codes

> Generated by `npm run gen:ai-pack` (scripts/ai-pack.ts) — do not edit. From `src/engine/errors/codes.ts` — each code, its phase, its severity and its meaning (`meaningOf`). Format version `ed0892bbbdf4`.

Every issue line of the import report carries one of these codes (`message-forms.md`). A code has one severity;
`import` is what reading the file found, `runtime` the update, and the other phases are the compile's.

## parse

| Code | Severity | Meaning |
|---|---|---|
| `PARSE_ERROR` | error | A formula or expression is not valid syntax. |

## name-resolution

| Code | Severity | Meaning |
|---|---|---|
| `UNKNOWN_SERIES` | error | A formula names a series the model does not have. |
| `UNKNOWN_DIMENSION` | error | An expression names a dimension the model does not have. |
| `UNKNOWN_LAYER` | error | An expression names a layer its dimension does not have. |
| `UNKNOWN_ELEMENT` | error | An expression names an element its dimension does not have. |
| `UNKNOWN_FUNCTION` | error | A formula calls a function that does not exist. |
| `KIND_MISMATCH` | error | A name was found, but it is a different kind of thing (a series, a dimension, a layer, an element) than its place in the formula needs. |
| `NAME_NOT_FOUND` | error | A formula names something the model does not have — no series, dimension, layer or element of that name. |
| `AMBIGUOUS_NAME` | error | A name in a formula matches more than one thing (for example an element of two dimensions); qualify it with its dimension or layer. |
| `MIXED_DIMENSIONS` | error | The parts of a dimensional expression belong to dimensions that have nothing in common, so together they select nothing. |
| `DIMENSION_NO_LAYERS` | error | A categorical dimension has no layers. |
| `MODEL_SPEC_CONSTRAINT` | error | A model object breaks a rule of the model definition — a reference to something missing, a roll-up or split-down rule without the series it needs, or an object left out of the model; the line names it. |
| `NO_DIMENSIONS_DECLARED` | error | A series declares no dimensions, and it needs at least one. |
| `DEFINITION_VALIDITY_ERROR` | error | An output range or axis definition is not valid as defined; the line says what is wrong. |
| `DEFINITION_VALIDITY_WARNING` | warning | An output range or axis definition has something worth knowing about; it still renders. |
| `BOOKKEEPING_REGENERATED` | warning | Part of the saved model's bookkeeping could not be read and was rebuilt as a recompile would; nothing of the model was left out. |
| `OR_ANCHOR_CELL_INVALID` | error | An output range's anchor is not a valid cell reference. |
| `OR_AXIS_EMPTY` | error | An output range's row or column axis has no items. |
| `OR_SERIES_REF_EMPTY` | error | An output range's series item has an empty expression. |
| `OR_DUPLICATE_SERIES` | error | The same series appears on both axes of an output range. |
| `OR_DUPLICATE_ALIAS` | error | Two series items in one output range declare the same `name :=` alias. |
| `OR_SHEET_NOT_FOUND` | error | An output range's anchor names a sheet the workbook does not have. |
| `OR_AXIS_DEFINITION_NOT_FOUND` | error | An output range uses an axis definition that does not exist. |
| `OR_SCOPE_EXPRESSION_INVALID` | error | An output range's element selection (scope) does not compile against its dimension. |
| `DSDATA_NO_DSE_IN_BLOCKS` | error | A `DS.DATA` call names no series on either axis. |
| `DSDATA_DSE_ACROSS_BOTH_AXES` | error | A `DS.DATA` call puts series on both axes; they must all be on one. |
| `DSDATA_DIM_ACROSS_BOTH_AXES` | error | A `DS.DATA` call names the same dimension on both axes. |
| `DSDATA_AD_NOT_FOUND` | error | A `DS.DATA` call names an axis definition (`AD:Name`) that does not exist. |
| `DSDATA_AD_INLINE_MIXED` | error | A `DS.DATA` axis mixes an axis definition with inline items; use one or the other. |
| `DSDATA_FILTER_DIM_NOT_ON_AXIS` | error | A `DS.DATA` filter names a dimension the call does not show on either axis. |
| `SL_DIM_MAPPING_MISMATCH` | error | A series loader's mapped dimensions differ from its target series' dimensions (one is missing from the mapping, or one is extra). |
| `SL_FIXED_ELEMENT_NOT_IN_DIM` | error | A series loader fixes a dimension to an element the dimension does not have. |
| `SL_TARGETS_DIM_SET_MISMATCH` | error | The targets of one bulk series loader do not all have the same dimensions. |
| `DG_FIXED_PARENT_NOT_IN_DIM` | error | A dimension generator fixes a parent element the dimension does not have. |
| `DG_TARGET_SEQUENTIAL` | error | A dimension generator targets a sequential dimension, whose elements only its parameters create. |
| `SL_TARGET_NOT_ELIGIBLE` | error | A series loader's target cannot receive data: it is missing, or calculated and not seedable. |
| `SL_LOAD_MODE_NOT_FED` | warning | A series loader uses the vector or scalar load mode, which no data source can feed today (every source delivers a table); it loads nothing. |

## dim-correctness

| Code | Severity | Meaning |
|---|---|---|
| `OR_SCOPE_AUTO_DROP` | warning | An output range's scope left an element out on its own (inert: nothing raises it today). |
| `DIMENSIONAL_INCOMPATIBILITY` | error | The dimensions of the parts of a formula do not fit its series. |
| `FILTER_DIM_NOT_IN_SUBJECT` | error | A filter names a dimension the filtered series is not bound to. |
| `DUPLICATE_DIMENSION_FILTER` | error | Two filters on one reference pin the same dimension. |
| `RULE_2_VIOLATION` | error | A formula's result has dimensions its series does not have. |
| `DIM_MISMATCH` | error | A filter names an element or layer of a dimension the filtered series is not bound to. |
| `EMPTY_TERMINAL_EXPANSION` | error | A `[*]` or `[_]` filter expands to no dimension, because every dimension of the series is already pinned. |

## shape

| Code | Severity | Meaning |
|---|---|---|
| `SHAPE_MISMATCH` | error | Parts of an expression have shapes that do not fit together (a single value, a list, a table). |
| `FUNCTION_ARG_SHAPE_MISMATCH` | error | A function argument has the wrong shape — a single value where a list is needed, or the reverse. |
| `VECTOR_IN_SCALAR_CONTEXT` | error | A list of values is used where one value is needed; aggregate it first (`SUM(…)`, `AVG(…)`, …). |
| `UNANCHORED_POSITIONAL` | error | An absolute position (`Layer[$N]`, `Layer[$a:$b]`) is used where its dimension is not in scope. |
| `DIM_RANGE_INVALID` | error | A range `Dim[a:b]` has ends that do not fit together (different layers, or not elements). |
| `POSITION_INDEX_ZERO` | error | An absolute position is `$0`; positions count from `$1` (or from `$-1` at the end). |
| `BARE_DIMENSION_FILTER` | error | A bare dimension name is used as a filter (`Revenue[Time]`); filter by an element, a layer or an offset instead. |

## runtime

| Code | Severity | Meaning |
|---|---|---|
| `DIM_RANGE_INVALID_DYNAMIC` | error | A range whose ends are computed turned out, at a cell, to have ends that do not fit together. |
| `CLUSTER_ROLE_RESTRICTION` | error | A reference inside a recurrence reads a total (a non-leaf element), which the recurrence cannot provide. |
| `INTERNAL_ERROR` | error | The engine found its own state invalid and could not go on. Report it. |
| `DIVISION_BY_ZERO` | warning | A division by zero; the cell holds an error value. |
| `TYPE_COERCION_FAILED` | error | A value could not be turned into the type its operator needs. |
| `VALUE_NOT_AVAILABLE` | error | A cell that had to hold a value held none. |
| `POSITION_INDEX_ZERO_DYNAMIC` | error | A computed absolute position came to `$0` at a cell; positions count from `$1`. |
| `DIM_SET_NOT_SINGLE_ELEMENT` | warning | A function needed exactly one element and got more than one at a cell; that cell holds an error value. |
| `CELL_DAG_CYCLE` | error | At calculation the cells of a recurrence turned out to depend on each other in a circle. |
| `UNANTICIPATED_CELL_DAG_EDGE` | error | At calculation a recurrence read a cell its structure did not foresee. |
| `CLUSTER_BROADCAST_FAILURE` | error | At calculation a recurrence could not spread across the dimensions it does not step along. |
| `IF_CONDITION_CYCLIC_CLUSTER` | error | An `IF` whose condition depends on its own recurrence made the calculation order circular. |
| `INPUT_RANGE_DUPLICATE_COLUMN` | error | An input range has two columns with the same header (headers match in any case). |
| `INPUT_RANGE_COLUMN_BAND_INVALID` | error | An input range's dimension-in-columns band does not match the range that was read. |
| `DATASOURCE_OUTPUT_TABLE_CONFLICT` | error | A data source reads an Excel table that is an output range's own table. |
| `DATASOURCE_RANGE_REF_NO_SHEET` | error | A data source's range reference names no sheet. |
| `EXCEL_REFERENCE_UNRESOLVED` | error | Excel could not find the range, named range or table a data source refers to. |
| `EXCEL_REFERENCE_NOT_EXAMINED` | error | Excel could not examine the range a data source refers to. |
| `DATA_SOURCE_NOT_DELIVERED` | error | A data source delivered no data this update. |
| `SERIES_LOADER_DUPLICATE_COORD_CONFLICT` | warning | Two rows of one source give different values for the same cell under `duplicateHandling: BLOCK`; the cell holds an error value. |
| `SERIES_LOADER_CROSS_LOADER_CONFLICT` | warning | Two loaders write the same cell of the same series; the cell holds an error value. |
| `SERIES_LOADER_UNKNOWN_DIM_ELEMENT` | warning | A source row names an element its dimension does not have (labels match ignoring case and surrounding spaces); the row is skipped. |
| `SERIES_LOADER_SEED_AXIS_NOT_SINGLE` | warning | A loader targets a calculated recurrence that steps along more than one dimension, so it cannot be seeded. |
| `DG_LAYER_REDEFINITION` | error | A dimension generator would place an existing element in another layer. |
| `DG_PARENT_REDEFINITION` | error | A dimension generator would give an existing element another parent. |
| `DG_LAYER_NOT_FOUND` | error | A dimension generator's layer column names a layer the dimension does not have. |
| `DG_PARENT_NOT_FOUND` | error | A dimension generator names a parent element the dimension does not have. |
| `DG_CHAIN_EXCEEDS_DIMENSION` | error | A dimension generator's chain of parent columns is deeper than the dimension's layers. |
| `DG_LAYER_PARENT_MISMATCH` | error | A dimension generator's element and its parent do not sit in neighbouring layers. |
| `SPLITDOWN_ZERO_DRIVER` | warning | A proportional split-down's driver adds up to zero where the value is split; those cells hold error values. |
| `SERIES_DATACELL_COLLISION` | error | A split-down tried to write a cell that already holds a value (data was entered both at a total and below it). |
| `SERIES_ROLLUP_DATACELL_COLLISION` | error | A roll-up tried to write a total that already holds a value. |
| `ROLLUP_ZERO_WEIGHT` | warning | A weighted-average roll-up's weights add up to zero; that total holds an error value. |
| `ROLLUP_REFERENCE_NOT_YET_CALCULATED` | warning | A roll-up formula read a total that is not calculated yet; that cell holds an error value. |
| `SL_COLUMN_NOT_FOUND` | warning | A column a series loader names is not in its source's header row; the loader loads nothing from it. |
| `DG_COLUMN_NOT_FOUND` | error | A column a dimension generator names is not in its source's header row. |
| `DG_ELEMENT_LAYER_COLLISION` | error | A generated element has the name of one of the dimension's layers. |
| `DG_NAME_RESERVED_IN_MODEL` | error | A generated element's name is already used in the model by something else. |
| `DG_NAME_INVALID_CHARACTER` | error | A generated element's name contains a reserved character (`; / [ ] { }`). |
| `SERIES_LOADER_VALUE_MISSING` | warning | A source row's value cell is empty, at a leaf; nothing is loaded for that cell. |
| `SERIES_LOADER_VALUE_NOT_NUMERIC` | warning | A source row's value cell holds text that is not a number; the cell holds an error value. |
| `SERIES_LOADER_VALUE_NOT_FINITE` | warning | A source row's value is a number too large to hold; the cell holds an error value. |
| `SERIES_LOADER_VALUE_ABOVE_LEAVES` | warning | Values were loaded above the leaves of a dimension whose split-down is NONE and whose roll-up is active; they stay there, so a series calculated at the leaves does not see them. |
| `RENAME_REWRITE_SKIPPED` | warning | A rename could not rewrite one formula's text; that formula still uses the old name. |
| `DECLARATION_ID_COLLISION_REPAIRED` | warning | A saved model held two objects with one id; the later one was given a new id. |
| `SERIES_LOADER_COORD_UNRESOLVED` | warning | A source row's coordinate could not be built (an empty dimension cell, or a fixed coordinate that does not resolve); the row is skipped. |
| `SERIES_LOADER_PAYLOAD_SHAPE_MISMATCH` | warning | A data source delivered data in a shape the loader's load mode does not read. |
| `SERIES_LOADER_TARGET_UNAVAILABLE` | warning | A loader's target series cannot receive this load (missing, or calculated with nothing to seed, or the model setting refuses it). |
| `SERIES_LOADER_OPEN_DIMENSION_NOT_FOUND` | warning | A vector loader's open dimension is not in the model. |
| `DG_PAYLOAD_SHAPE_UNSUPPORTED` | error | A dimension generator was given data in a shape it cannot read. |
| `DG_TARGET_DIMENSION_NOT_FOUND` | error | A dimension generator's target dimension is not in the model. |
| `DG_ELEMENT_ADD_FAILED` | error | A generated element could not be added to its dimension. |
| `DG_LAYER_INVARIANT_VIOLATED` | error | A dimension generator placed an element at or above its parent's layer. |
| `DATA_SOURCE_EMPTY` | warning | A data source delivered a well-formed table with no rows; nothing loads from it, and nothing else is affected. |
| `UPDATE_DID_NOT_FINISH` | error | The update stopped before it finished; what it found before stopping is listed after this line. |
| `OR_RENDER_OVERFLOW` | error | An output range would write over cells that already hold data, so it was not written. Move it, or allow it to overwrite. |
| `OR_RENDER_OVERLAP` | error | Two output ranges would write the same cells, so neither was written. |
| `OR_RENDER_WRITE_FAILED` | error | Writing an output range to its sheet failed. |
| `OR_RENDER_COMPILE_FAILED` | error | An output range that does not compile was written as its error: its anchor cell carries the message. |
| `OR_RENDER_RUNTIME_FAILED` | error | An output range could not calculate some of its cells, and they are marked `[error]` on the sheet. The line counts them and gives the cause: the formula's own fault, or, when Axmo itself failed, the first such cell (the series as written in the range, and its elements) and a defect to report. |
| `OR_TABLE_ORDER_NOT_APPLIED` | warning | A table-mode output range's column order changed, but user columns inside the table keep the columns from being reordered. The data is correct. |
| `SERIES_CELLS_FAILED` | warning | Cells of a series could not be calculated and hold error values; anything calculated from them holds an error too. The reasons are on the line or attached beneath it. |
| `SERIES_CELLS_CARRIED_ERROR` | warning | Cells of a series hold an error carried from the series the line names. |
| `SERIES_SEED_OVERWRITTEN` | warning | Data was loaded into a calculated series' cell that its formula computes; the formula's result replaced it. |
| `VECTOR_LENGTH_MISMATCH` | warning | Two element-wise operands of different lengths met in one expression. |
| `FUNCTION_DID_NOT_CONVERGE` | warning | A root-finding function (`IRR`, `RATE`) did not converge; supplying an explicit guess may help. |
| `DSDATA_CELL_FAILED` | error | A `DS.DATA` call on the sheet could not produce its result; the line names the call's cell. |
| `CHECK_HOST_SHORTFALL` | error | `axmo:check` only: the stand-in host could not do what Excel would, so the report is not a full check. |

## dep-graph

| Code | Severity | Meaning |
|---|---|---|
| `CYCLE_DETECTED` | error | Series depend on each other in a circle that is not a progressive recurrence along a sequential dimension. |
| `MISSING_DEPENDENCY` | error | A dependency the calculation needs is missing. |
| `COMPUTE_DAG_CYCLE` | error | The calculation order contains a circle that is not a progressive recurrence. |

## cluster-analysis

| Code | Severity | Meaning |
|---|---|---|
| `NON_PROGRESSIVE_CYCLE` | error | A self- or mutually-referencing formula does not step consistently along one sequential dimension (only a backward or only a forward offset). |
| `INPUT_SERIES_IN_CLUSTER` | error | An input series is part of a circle of mutually-referencing formulas. |
| `CLUSTER_INTERNAL_OFFSET` | error | A reference inside a recurrence reads a period the recurrence has not reached yet. |
| `CLUSTER_MIXED_CONTRIBUTOR` | error | A series in a recurrence mixes stepping and non-stepping references to the recurrence. |
| `CLUSTER_AXIS_MISMATCH` | error | The series of one recurrence do not all step along the same sequential dimension. |

## import

| Code | Severity | Meaning |
|---|---|---|
| `FORMAT_FILE_UNREADABLE` | error | The file is not a readable `.axmo` container or model YAML file: it could not be opened, or it holds no model. |
| `FORMAT_YAML_SYNTAX` | error | The model text is not valid YAML, so nothing in it was read. |
| `FORMAT_VERSION_UNSUPPORTED` | error | The document's format version (`axmo:`) is missing, or is not a version this release reads. |
| `FORMAT_UNKNOWN_KEY` | error | A key the format does not define at this place in the file. |
| `FORMAT_MISSING_KEY` | error | A key the format requires at this place is absent (an output range block that names no kind is one). |
| `FORMAT_EMPTY_VALUE` | error | A key is stated with an empty value, or a value that must not be empty is empty. State a value, or leave the key out. |
| `FORMAT_RETIRED_KEY` | warning | A key the format no longer reads. It is ignored on import, and the rest of the file is read. |
| `FORMAT_RETIRED_VALUE` | error | A value the format no longer accepts (a retired roll-up method). |
| `FORMAT_NOT_A_MAPPING` | error | A value that must be a mapping (`key: value` lines) is something else. |
| `FORMAT_NOT_A_LIST` | error | A value that must be a list is something else. |
| `FORMAT_WRONG_TYPE` | error | A value of the wrong type: text where a number or yes/no is expected, a list where one value is expected, and so on. |
| `FORMAT_VALUE_NOT_ALLOWED` | error | A value outside the set the format allows at this place; the line lists the allowed ones. |
| `FORMAT_NOT_A_NAME` | error | A value that must be a name (of an element, a column, a dimension, an axis definition, an alias) is not one. |
| `FORMAT_NOT_AN_ADDRESS` | error | A value that must be a sheet-qualified cell or range address is not one. |
| `FORMAT_KEYS_EXCLUSIVE` | error | Two keys that cannot be stated together are both stated (or an output range block names more than one kind). |
| `FORMAT_SERIES_GROUP` | error | An output range's series group is where the format does not allow it: a second group, a group between dimension blocks, or groups on both axes. |
| `FORMAT_TREE_NOT_CHILDREN` | error | A dimension tree element holds a value that is not its children (nothing, a list of child names, or a mapping of child elements). |
| `FORMAT_TREE_PREFIX_NOT_A_LAYER` | error | A dimension tree entry's `Layer/` prefix names no layer of the dimension. |
| `FORMAT_TREE_BELOW_LAST_LAYER` | error | A dimension tree entry sits below the dimension's last layer. |
| `FORMAT_TREE_PLACED_TWICE` | error | A dimension tree element is placed differently (another layer or parent) by two entries. |
| `FORMAT_TIME_PARAMETERS` | error | A time dimension's parameters do not agree (an end before its start, an unknown level, …), or its elements could not be generated from them. |
| `FORMAT_DATA_NOT_NUMERIC` | warning | Cells of the file's `data` section hold values that are not numbers the model can hold. Those cells become error values; the rest imports. |
| `FORMAT_INVALID` | error | Any other refusal of the file's shape, in the reader's own words. |
| `IMPORT_BUILD_REFUSED` | error | The file was read, but its model could not be built from it. The open model is unchanged. |
| `IMPORT_FAILED` | error | The import stopped before it finished (a sheet could not be created, or another failure). The open model is unchanged unless the line says otherwise. |
| `IMPORT_DATA_NOT_RESTORED` | warning | Part of the file's data or sheet structures (a table, a named range) could not be restored into the workbook. |
| `IMPORT_TABLE_REPLACED` | warning | A table-mode output range's previous table was replaced, including columns the user added there that the file does not carry. |
| `IMPORT_OUTPUT_NOT_CLEARED` | warning | An output range of the model the import replaced could not be cleared from its sheet. |
| `IMPORT_USER_COLUMNS_NOT_APPLIED` | warning | User columns the file carries could not be put back into their output range's table, or a user column's formula resolved to an error. |
| `WORKBOOK_UNREADABLE` | error | The workbook tool only: the file is not a workbook it can read (an `.xlsx` package holding `xl/workbook.xml`). |
| `WORKBOOK_NOT_AXMO` | error | The workbook tool only: the workbook holds no Axmo model — it is not an Axmo workbook, or a tool that does not keep custom XML parts saved it and removed the model. |
| `WORKBOOK_DEFINITION_UNREADABLE` | error | The workbook tool only: the workbook's model could not be read; the line quotes why. |
| `WORKBOOK_DEFINITION_TOO_NEW` | error | The workbook tool only: the workbook's model was saved in a newer definition version than the tool reads. |
| `WORKBOOK_OBJECT_LEFT_OUT` | warning | The workbook tool only: an object of the workbook's model was left out when it was read, so the model file does not hold it; the line quotes its definition error. |
| `WORKBOOK_MODEL_NOT_WRITABLE` | error | The workbook tool only: the workbook's model stores a value the file format does not have, so no model file is written; the line names the object, the field and the value. |
| `EXTRACT_DATA_NOT_READ` | warning | `extract --depth complete` only: the input cells could not be read from the file, so the data section is empty, as the add-in's Export writes it then; the line says why. |
| `EXTRACT_FORMULA_NOT_CALCULATED` | warning | `extract --depth complete` only: formula cells in the data hold no saved value (a tool that does not calculate saved the workbook), so they are written empty; the line names the first cells. |
| `APPLY_DATA_NOT_APPLIED` | warning | `apply` only: the model file's data section was not applied — input cells are changed only in Excel. |
| `APPLY_OUTPUT_RANGE_REMOVED` | warning | `apply` only: an Output Range of the workbook is not in the new model (removed or renamed); the cells it last wrote stay until they are cleared in Excel. |
| `APPLY_OUTPUT_RANGE_MOVED` | warning | `apply` only: an Output Range moved to another anchor; the cells it last wrote stay until they are cleared in Excel, and its new place is checked for data as a new range's is. |
| `APPLY_DSDATA_BROKEN` | warning | `apply` only: a `DS.DATA` call in the workbook does not compile against the new model; the line names its cell and quotes the compile. |
| `APPLY_DSDATA_NOT_CHECKED` | warning | `apply` only: a `DS.DATA` call could not be checked against the new model, because an argument is not text. |
| `APPLY_SOURCE_NOT_IN_WORKBOOK` | error | `apply` only: a data source of the model file refers to a table, a defined name or a sheet the workbook does not hold. The line names the source, the reference and what is missing. |
| `APPLY_LOADER_COLUMN_NOT_IN_WORKBOOK` | warning | `apply` only: a loader or generator names a column its source does not have in the workbook's cells as last saved; the line is the loader's own message, at the loader. |
| `APPLY_OUTPUT_SHEET_NOT_IN_WORKBOOK` | warning | `apply` only: an Output Range is anchored on a sheet the workbook does not hold. Update does not create a sheet, so the range is not written until the sheet is added in Excel; the line names the range and the sheet, at the range. |