Error Codes

Status: Draft · Spec version 0.6 · Normative

This document is the error code registry that the specification requires. It lists every condition of static validation and every evaluation fault, with the code that a diagnostic reports for it.

The scheme

A code has the form <area>.<condition>. Both parts match ^[a-z][a-z0-9_]*$.

expr.unresolved_path
catalog.missing_scope
fault.division_by_zero

Areas.

Area	Conditions in
doc	Document structure, names, and modifiers
serial	The serialization subset
expr	Expression syntax, resolution, and typing
filter	Filters and filter packages
flow	Control flow
tmpl	Templates
state	The states profile
trigger	Triggers
catalog	Manifests, connections, and overlays
recovery	Failure and recovery policy
agent	Agent nodes
run	Sandboxed code
capability	Declared capabilities
fault	Evaluation faults, which occur at run time

Stability. A code is never removed, and never reassigned to another condition. A condition that a later spec version splits keeps the original code for the original condition, and the new part takes a new code.

Allocation. A code is added by a spec revision, together with the requirement that produces it. A requirement without a code is a defect in this document.

Reporting. A diagnostic MUST report one code, the path of the offending construct within the document, and a source location. Message text is implementation-defined. An implementation MAY report more than one diagnostic for one document.

Every code below is a validation error, reported before any action executes, except the fault area. A fault code names a condition that occurs during evaluation, and is recorded as a step outcome.

---

doc — document structure

Code	Condition
doc.unknown_key	An unknown top-level key or an unknown construct key. A key beginning with x- is never unknown.
doc.unknown_modifier	A modifier that the modifier table does not permit on that body kind.
doc.missing_body	The file declares neither steps nor states.
doc.both_bodies	The file declares both steps and states.
doc.states_without_initial	A states file that does not declare initial.
doc.initial_without_states	A steps file that declares initial.
doc.duplicate_id	Two steps in one scope share an id.
doc.reserved_name	A step id, as binding, into binding, outputs name, or accepts name repeats a reserved name.
doc.optional_with_must_succeed	One step declares both optional and must_succeed.
doc.invalid_name	A declared name does not match ^[a-z][a-z0-9_]*$.

serial — serialization

Code	Condition
serial.anchor_or_alias	The document uses a YAML anchor or alias.
serial.tag	The document uses a YAML tag.
serial.multi_document	The stream holds more than one document.
serial.implicit_type	An unquoted scalar could be read as more than one type.
serial.unquoted_type_expression	A type expression appears unquoted.

expr — expressions

Code	Condition
expr.syntax	The expression violates the expression grammar.
expr.chained_comparison	A comparison is chained, as a < b < c. Comparison is non-associative.
expr.unresolved_path	A path names no binding in scope at that point.
expr.non_boolean_guard	A guard position holds an expression whose type is known and is not bool.
expr.invalid_duration_literal	A duration literal violates the duration grammar.
expr.invalid_timestamp_literal	A timestamp violates the timestamp grammar.

filter — filters and packages

Code	Condition
filter.unknown	The name matches no core filter and no filter of a resolved package.
filter.signature	An argument violates the filter’s declared signature.
filter.package_unavailable	A referenced filter package cannot be resolved.
filter.package_missing_fixtures	A filter package does not ship fixtures for every filter.
filter.where_op_not_literal	The op argument of where is not a string literal.
filter.where_op_unknown	The op argument of where is outside its closed set.
filter.nested_element_filter	The argument of each or keep holds an each or a keep.
filter.current_out_of_scope	current is referenced outside the argument of each or keep.
filter.unknown_time_directive	A literal format_time pattern holds a directive outside the closed directive set.

flow — control flow

Code	Condition
flow.route_not_exhaustive	A route over a value with a declared enum domain leaves a member uncovered.
flow.route_label_out_of_domain	A route case label is outside the declared enum domain.
flow.missing_else	A route or a choose declares no else.
flow.missing_max	A for_each or a repeat declares no max.
flow.invalid_max	max is neither a positive integer nor unbounded.
flow.unbounded_repeat	A repeat declares max: unbounded.
flow.invalid_on_error	An on_error value other than continue or fail_fast.
flow.duplicate_branch_name	Two parallel branches share a name.
flow.cross_branch_reference	A parallel branch references another branch’s bindings.
flow.wait_arms	A wait declares neither or both of for and until.
flow.wait_for_without_timeout	A wait_for declares no timeout.
flow.missing_correlation_value	A match omits a value for a key that correlate_on declares.
flow.path_into_void_step	A path names the id of a wait step or a stop step, which bind nothing.
flow.call_missing_input	A call omits an input that the callee declares required.
flow.call_unknown_input	A call supplies a name that the callee does not declare.
flow.call_unknown_output	A path names an output that the callee does not declare.
flow.call_without_outputs	A path enters a call on a callee that declares no outputs.
flow.call_depth	The callee of a call itself contains a call.

tmpl — templates

Code	Condition
tmpl.value_extra_key	A value step holds a key other than value and when.
tmpl.render_extra_key	A render step holds a key other than render, with, and when.
tmpl.path_not_literal	A render path holds an expression.
tmpl.path_not_found	A render path names no file and no directory.
tmpl.inline_body_keys	An inline render map does not hold exactly one of text, html, json, parts.
tmpl.duplicate_part	Two parts resolve to one name.
tmpl.invalid_part_name	A part name does not match ^[a-z][a-z0-9_]*$.
tmpl.variable_unsupplied	The body references a variable that is unguarded and that with does not supply.
tmpl.variable_unused	with supplies a key that the body never references.
tmpl.syntax	The body violates the template block grammar.
tmpl.partial_context_mismatch	A partial is included from a template of another escape context.
tmpl.partial_nesting	A partial includes another partial.
tmpl.partial_cycle	A partial includes itself, directly or transitively.

state — the states profile

Code	Condition
state.subscription_without_event	An on entry declares no event.
state.transition_without_target	A transition declares neither goto nor route.
state.unknown_state	initial or a goto names a state that is not declared.
state.no_final_state_reachable	No final state is reachable from the initial state.
state.accepts_missing_required	A transition omits a name that the target’s accepts declares required.
state.accepts_unknown_name	A transition supplies a name that the target’s accepts does not declare.
state.accepts_on_initial	The initial state declares accepts.

trigger — triggers

Code	Condition
trigger.binding_collision	A trigger binding repeats a root-scope step id, and no as resolves it.
trigger.missing_as	A multi-trigger file has an entry without as.
trigger.into_on_single_trigger	A single-trigger file declares into.
trigger.into_incomplete	Some entries of a multi-trigger declaration declare into and others do not.
trigger.into_shape_mismatch	Two into entries do not bind an identical key structure.
trigger.batch_with_queue_by	One trigger entry declares both batch and queue_by.

catalog — manifests, connections, overlays

Code	Condition
catalog.unknown_connector	A reference names a connector that the resolved catalog does not declare.
catalog.unknown_action	A reference names an action that the connector’s manifest does not declare.
catalog.unknown_event	A reference names an event that the connector’s manifest does not declare.
catalog.invalid_argument	An argument violates the input schema of the named action or trigger.
catalog.reserved_namespace	A resolved catalog binds a package other than the canonical one to a canonical or reserved namespace.
catalog.missing_scope	The resolved connection does not grant a scope that a named action or trigger declares.
catalog.incomplete_connection	The resolved connection holds no value for a required connection parameter.
catalog.invalid_connection_parameter	A connection parameter value violates its declared type or its pattern.
catalog.host_parameter_without_pattern	A manifest declares in: host with no pattern, and does not declare self_hosted.
catalog.external_ref	A $ref is not a local pointer of the form #/schemas/<name>.
catalog.manifest_unknown_key	A manifest holds a key that the manifest key reference does not list.
catalog.field_declaration_invalid	A field declaration holds an unknown key, declares both type and $ref, declares neither, or declares both required: true and default.
catalog.unrefined_member_access	Member access enters an extension region for which no overlay is resolved.
catalog.overlay_unknown_field	Member access names a field that the resolved overlay does not declare.
catalog.overlay_undeclared_argument	An argument field inside an extension region is not declared by the overlay.
catalog.overlay_declares_extension_point	An overlay declares an extension point of its own.
catalog.overlay_refines_ordinary_schema	An overlay refines a schema that the manifest does not mark defined_by: connection.

recovery — failure and recovery

Code	Condition
recovery.retry_on_non_idempotent	on_unknown: retry on an action that the manifest does not declare idempotent.
recovery.retry_without_key	on_unknown: retry on a step that supplies no idempotency_key, while the action declares an idempotency_param.
recovery.reconcile_without_policy	A reconcile key on a step whose on_unknown is not reconcile.
recovery.reconcile_incomplete	An on_unknown: reconcile step whose reconcile is absent, omits steps or outcome, or omits result while the action declares an output.
recovery.redo_set_uncompensated	A redo set holds a step that is not naturally idempotent, is not idempotent with a declared key, and does not declare undo.

agent and run

Code	Condition
agent.missing_budget	An agent declares no budget.
agent.empty_budget	A budget declares no defined bound.
agent.tool_not_in_catalog	tools names an action outside the resolved catalog.
run.unregistered_language	The language of a run step is not in the registry of run languages.

capability

Code	Condition
capability.required	The file uses a construct that requires a capability the implementation does not declare. The diagnostic MUST name the capability.

fault — evaluation faults

These occur during evaluation, not during validation. The fault rules state how each is handled.

Code	Condition
fault.division_by_zero	Division or modulo by zero.
fault.integer_overflow	An integer result outside the int range.
fault.operand_type	An operator applied to a value outside its domain: arithmetic on a non-number, % on a non-integer, or not, and, or on a non-boolean.
fault.non_finite	An operation that would produce NaN or an infinity.
fault.ordered_comparison_types	An ordered comparison whose operands are not two values of one ordered type, including a comparison against null.
fault.mixed_ordering	An ordering filter applied to a collection that mixes ordered types.
fault.membership_operand	The right operand of in is not a list, a map, or a string.
fault.conversion	A conversion filter cannot convert a value unambiguously.
fault.filter_signature	A filter is applied outside its declared signature, where the input’s type could not be established statically.
fault.filter_argument	A computed filter argument is invalid at run time.
fault.unknown_time_directive	A computed format_time pattern holds a directive outside the closed set.
fault.non_boolean_guard	A guard yields a value that is not a boolean, where the type could not be established statically.
fault.template_render	An interpolation in a template body faults.