Diagnostics

Culsma diagnostics are stage-owned.

Family	Stage	Typical cause
LOAD_*	source loading	missing source, duplicate protocol, unknown entry
SEM_*	semantic validation	unknown operation, missing arg, invalid content kind
TYPE_*	type/unit checking	unknown unit, dimension mismatch
PLAN_*	plan lowering	unknown protocol reference, call argument issue
RT_*	runtime	driver failure, scheduler/material orchestration issue
MAT_*	material compute	insufficient material, overflow, conservation failure

The main diagnostic guide describes emitted diagnostics. Roadmap-only diagnostic codes are kept out of this page.

Diagnostics carry severity. error diagnostics block the current stage or run. warning diagnostics record compatibility behavior without making the result fail.

Current warning examples:

Code	Meaning
SEM_CONTENT_TAXONOMY_COMPAT_NORMALIZED	Older or non-canonical content taxonomy was normalized to a supported kind/type.
SEM_FIELD_PROGRAM_FIELD_ALIAS	The legacy field_program.field spelling is accepted as an alias for voltage; use voltage in new source.

Scientific Model Diagnostics

Material allocation and relationship decisions must be resolved before runtime commits an operation's candidate material state. These are errors, not warnings that permit a guessed split:

Code	Meaning
MAT_SCIENTIFIC_MODEL_UNRESOLVED	The selected provider could not resolve a required decision from the available facts.
MAT_SCIENTIFIC_MODEL_FAILED	Scientific-model resolution failed.
MAT_SCIENTIFIC_MODEL_REJECTED	The proposed decision or its contract failed validation.

For an unresolved allocation, provide an applicable scientific-model decision or declare the intended per-content allocation with component_fates. transitions declares relationship state and cannot replace missing allocation fractions. Invalid decisions must be corrected; runtime does not substitute a 50/50 allocation or commit a partial result. The CLI may also report RT_MATERIAL_ERROR and RT_ABORTED_AFTER_FAILURE when it stops the run.

See Material Partition Estimates for decision precedence and the built-in provider's scope.

Material Transition Diagnostics

Author-controlled sep.transitions is checked first at the semantic stage and again against live material state at the material-compute stage.

Semantic diagnostics reject errors that are decidable from source and compiled bindings:

Code	Meaning
SEM_MATERIAL_TRANSITIONS_SHAPE_INVALID	transitions is not a list of typed transition(...) values.
SEM_MATERIAL_TRANSITION_SHAPE_INVALID / SEM_MATERIAL_TRANSITION_ARGS_INVALID	A transition has the wrong call shape, missing arguments, or unknown arguments.
SEM_MATERIAL_SELECTOR_INVALID / SEM_MATERIAL_SELECTOR_CONTAINER_MISMATCH	A selector is not a static same-sample materials[index] or materials.get(entry_id) expression.
SEM_MATERIAL_TRANSITION_OUTPUT_INVALID	output is not a member of the concrete program's output enum.
SEM_MATERIAL_TRANSITION_TARGET_INVALID	to is not an author-settable MaterialRelation member. Strings, bare names, unknown members, and UNRESOLVED are rejected.
SEM_MATERIAL_TRANSITION_ASSOCIATION_REQUIRED	A component-bound target omits associated_with.
SEM_MATERIAL_TRANSITION_ASSOCIATION_FORBIDDEN / SEM_MATERIAL_TRANSITION_ASSOCIATION_INVALID	An association is supplied for the wrong relation or uses an invalid selector.

Material-compute diagnostics depend on the live entries and selected output:

Code	Meaning
MAT_MATERIAL_TRANSITIONS_SHAPE_INVALID / MAT_MATERIAL_TRANSITION_SHAPE_INVALID	Runtime receives an invalid serialized transition collection or item.
MAT_MATERIAL_SELECTOR_INVALID / MAT_MATERIAL_SELECTOR_CONTAINER_MISMATCH	Runtime receives an invalid selector shape or a selector for another source container.
MAT_MATERIAL_INDEX_OUT_OF_RANGE	The selected live-entry index does not exist.
MAT_MATERIAL_ENTRY_ID_NOT_FOUND / MAT_MATERIAL_ENTRY_ID_AMBIGUOUS	Exact ID selection resolves to zero or multiple live entries.
MAT_MATERIAL_ENTRY_INVALID / MAT_MATERIAL_RELATION_INVALID	The selected entry or its current relationship state is invalid.
MAT_MATERIAL_TRANSITION_OUTPUT_INVALID / MAT_MATERIAL_TRANSITION_TARGET_INVALID	The serialized output enum or target relation is invalid for this transition.
MAT_MATERIAL_TRANSITION_OUTPUT_EMPTY / MAT_MATERIAL_TRANSITION_OUTPUT_UNRESOLVED	The selected subject cannot be resolved with positive quantity in the requested output.
MAT_MATERIAL_TRANSITION_DUPLICATE	More than one transition targets the same subject and output.
MAT_MATERIAL_TRANSITION_ASSOCIATION_REQUIRED / MAT_MATERIAL_TRANSITION_ASSOCIATION_FORBIDDEN	The target relation's association contract is not satisfied.
MAT_MATERIAL_TRANSITION_ASSOCIATION_KIND_INVALID / MAT_MATERIAL_TRANSITION_ASSOCIATION_OUTPUT_EMPTY	The association target is not a component entry or has no positive quantity in the same output.
MAT_AUTHOR_TRANSITION_SOURCE_UNRESOLVED / MAT_AUTHOR_TRANSITION_RELATION_INVALID	The low-level transition boundary cannot establish a valid current source relation.

Any material-transition error rejects the complete transition candidate before commit. Runtime does not partially mutate the material state.