Error Codes

When the CLI fails, it returns a structured error code you can search for in docs or share with the team.

Format

Errors are reported as:

• code (e.g., E201)
• message (human explanation)
• sometimes a path (where it failed in the spec)

Codes

Code	Meaning
E100	YAML Syntax Error
E101	Missing Required Section
E102	Unknown Section
E103	Type Mismatch During Deserialization
E200	Missing Required Field
E201	Invalid Field Type
E202	Invalid Enum Value
E203	Missing Probability (Manual Distribution)
E401	Unknown Package Reference
E402	Unknown Module Reference
E403	Circular Import Detected
E404	Equipment Item Without Equipment Block
E405	Duplicate Package Path
E409	Conflicting Inline Block and Explicit Link
E410	Missing Required Name in Inline String Block
E414	Relative Import Escapes Package
E501	Unknown Definition Reference
E502	Circular Definition Inheritance
E503	Definition Depth Exceeds Limit
E504	Ambiguous Definition Reference
E505	Non-Scalar Mapping Key
E506	Unsupported YAML Feature
E507	Unknown Directive
E508	Invalid Definition Type
E509	Duplicate Definition
E510	Invalid Definition Name
E511	Invalid $remove Directive
E512	Exported Definition Not Found
E520	Unknown Variable Reference
E523	Type Error in Variable Access
E524	Index Out of Range
E525	Missing Object Property
E532	Invalid Variable Name
E533	Duplicate Variable Declaration
E534	Invalid Variable Type
E535	Exported Variable Not Found
E536	Imported Variable Not Exported
E540	$with Without $extends
E541	Invalid $with Value
E542	Invalid $with Binding Name
E543	Invalid $with Binding Value
E544	Missing Required Parameter
E545	Invalid $params Declaration

Groups

• E1xx Parse errors
• E2xx Schema / validation errors
• E4xx Import / module / inline expansion errors (including E405 workspace validation, E409/E410 inline block validation, E414 boundary validation)
• E5xx Definition, expansion, variable, parameter binding, and filter errors

Inline Expansion Errors

E409: Conflicting Inline Block and Explicit Link

An enchantPassivityCategories create or upsert operation specifies both passivityLink and a passivities inline block. Only one is allowed — the inline block auto-assembles the link.

enchantPassivityCategories:
  create:
    - enchantPassivityCategoryId: 120314
      passivityLink: "99000001"     # E409 - cannot combine with passivities
      passivities:
        create:
          - id: 99000001
            category: Equipment
            name: "passive"
            kind: 1
            value: 100.0

Remove either passivityLink or passivities. When using the inline block, the link is computed automatically.

E410: Missing Required Name in Inline String Block

A passivityStrings inline block on a create or upsert passivity operation is missing the required name field.

passivities:
  create:
    - category: Equipment
      id: 100001
      name: "passive"
      kind: 1
      value: 100.0
      passivityStrings:
        tooltip: "Some tooltip"    # E410 - missing 'name'

Add name to the passivityStrings block. The name field is required for create and upsert; updates do not require it.

Variable Errors

E523: Type Error in Variable Access

Indexed variable access requires the variable to be the correct type:

variables:
  HP: 100

items:
  create:
    - id: 1
      value: $HP[$idx]     # E523: HP is not an array

Variants: expected array, expected integer (for index), expected mapping (for property access).

E524: Index Out of Range

Array index exceeds the variable’s array length:

variables:
  STEPS: [10, 20, 30]
  IDX: 5

items:
  create:
    - id: 1
      step: $STEPS[$IDX]   # E524: index 5, but array has 3 elements

E525: Missing Object Property

Property access on an array element references a property that doesn’t exist on the mapping:

# E525: property 'missing' not found on object

E532: Invalid Variable Name

The variable name does not match [A-Za-z_][A-Za-z0-9_]* or uses a reserved name:

variables:
  extends: foo       # E532: 'extends' is reserved

Reserved names: extends, remove, with, params.

E533: Duplicate Variable Declaration

The same variable name appears twice in one module’s variables: section:

variables:
  HP: 100
  HP: 200            # E533

Note: YamlDotNet may reject duplicate YAML keys at the parser level before this validation runs.

E534: Invalid Variable Type

Variable value is a mapping or a list containing non-scalar elements:

variables:
  STATS:
    hp: 100
    mp: 50            # E534: Mappings not allowed

Variables must be scalars or flat scalar lists. For complex data reuse, use definitions with $extends.

E535: Exported Variable Not Found

A variable listed in exports.variables does not exist in the module’s variables: section and is not in its effective imported scope (variables explicitly imported via use.variables):

variables:
  BASE_HP: 1000

exports:
  variables:
    - BASE_HP
    - NONEXISTENT     # E535: not declared locally or imported

Re-export without import also triggers E535:

imports:
  - from: package-a       # No use.variables — no variables imported

exports:
  variables:
    - INTERNAL_VALUE       # E535: not in local variables or effective imported scope

See Variables for valid re-export syntax.

E536: Imported Variable Not Exported

A variable requested via use.variables is not listed in the source module’s exports.variables:

imports:
  - from: shared/constants.yaml
    use:
      variables:
        - SECRET       # E536: Not in source module's exports.variables

See Variables for full variable documentation.

Parameter Binding Errors

E540: $with without $extends

$with requires $extends as a sibling directive:

result:
  create:
    - id: 1
      $with: { X: 2 }     # E540: No $extends sibling

E541: Invalid $with value

$with must be a YAML mapping:

result:
  create:
    - $extends: Template
      $with: not_a_mapping   # E541: Expected mapping, found scalar

E542: Invalid $with binding name

Binding names must match [A-Za-z_][A-Za-z0-9_]*:

result:
  create:
    - $extends: Template
      $with: { "123bad": 1 }  # E542: Invalid binding name

E543: Invalid $with binding value

Binding values must be scalars or scalar lists. Mappings and sequences containing non-scalar elements are not allowed:

result:
  create:
    - $extends: Template
      $with:
        X:
          nested: value       # E543: Mappings not allowed

E544: Missing required parameter

A definition with $params is extended without providing all required parameters:

definitions:
  Item:
    $params: [SOURCE, TARGET]
    source: $SOURCE
    target: $TARGET

result:
  create:
    - $extends: Item
      $with: { SOURCE: 1 }    # E544: Missing 'TARGET'

Required parameters can be satisfied by $with bindings or file-scoped variables.

E545: Invalid $params declaration

$params must be a sequence of valid identifier strings with no duplicates:

definitions:
  Item:
    $params: not_a_list       # E545: Expected sequence of strings
    id: 1

definitions:
  Item:
    $params: [ID, ID]         # E545: Duplicate parameter name 'ID'
    id: $ID

See Definitions for full $with and $params documentation.