Configuration errors

Configuration errors are raised while immutable definitions, bindings, or composition roots are checked. They do not represent a partially running session. Extract the typed value, fix the named field or kind, and call the constructor again.

Rig and loop definitions

rig.DefinitionError has Kind, Name, and an optional wrapped Cause. Its exact kinds cover the composition graph:

loop.DefinitionError has Kind, Field, Value, and Cause. Its exact definition kinds include missing_name, invalid_client, invalid_model, nil_option, duplicate_option, invalid_tool, invalid_tool_limits, invalid_drain_timeout, invalid_middleware, invalid_access_gate, invalid_engine, invalid_runtime_context, invalid_delegate, invalid_delegation, invalid_mode, duplicate_mode, missing_initial_mode, invalid_initial_mode, missing_policy_revision, invalid_policy_revision, missing_context_counter, invalid_context_counter, missing_inference_capability, invalid_inference_capability, incompatible_context_counter, missing_context_policy, conflicting_context_policy, invalid_context_observation, invalid_compaction, invalid_mode_binding, invalid_output_schema, reserved_tool_name, duplicate_context_transport, and invalid_context_transport.

loop.BindError is the next boundary. Its kinds are invalid_definition, invalid_context, duplicate_definition_name, duplicate_tool_name, invalid_tool_info, invalid_access_gate, invalid_runtime, invalid_session_id, and invalid_loop_id.

Hustles, gates, and hooks

hustle.DefinitionError uses Kind, Field, and Cause. Its exact kinds are missing_name, reserved_name, nil_option, duplicate_option, invalid_participation, invalid_model_source, missing_model_source, invalid_client, invalid_model, invalid_timeout, invalid_limits, invalid_system_prompt, invalid_prompt_revision, missing_policy_revision, invalid_policy_revision, invalid_output_schema, invalid_evidence_tools, and invalid_retry_policy. Binding and resolution use hustle.BindError kinds invalid_definition, invalid_context, missing_model_resolver, and invalid_evidence_tools, followed by hustle.ResolveError kinds invalid_context, invalid_loop_id, model_failed, and invalid_binding.

Gate construction has two distinct typed families. gate.GateValidationError uses restorable_not_allowed and origin_invalid. Runtime evaluation uses gate.EvaluationError kinds rule_match_failed, denied, action_invalid, approver_missing, approval_required, approval_failed, writer_missing, write_failed, issuer_missing, grant_version_unsupported, and grant_failed. Payload decoding additionally has typed unknown, nil, encode, decode, and request-decode errors.

hook.ConfigError distinguishes unknown_operation, operation_not_guardable, nil_guard, nil_around, missing_policy_revision, unexpected_policy_revision, invalid_policy_revision, and invalid_denial. An intentional guard refusal is *hook.Denial, not a configuration error; classify it with hook.AsDenial.

Bindings and tools

Tool definition and preparation errors are also configuration boundaries:

Rig workspace placement has its own typed boundary. WorkspacePlacementError kinds are multiple_placements, nil_store, nil_leaser, empty_root, canonicalize_failed, lease_name_invalid, and workspace_tool_without_placement. PersistenceOverlapError reports the canonical persistence path and workspace root. Per-call NewSession options use SessionOptionError kinds nil_option, duplicate_seed, and empty_seed.

Recovery boundary

These errors occur before durable session construction succeeds. Do not call RestoreSession for an invalid immutable definition and do not create a replacement merely because a Define or Bind call failed. Correct the configuration, then rebuild the Rig or binding.

configured, err := definition.Bind(ctx, bindContext)
if err != nil {
	var bindErr *loop.BindError
	if errors.As(err, &bindErr) {
		log.Printf("loop bind kind=%s name=%s", bindErr.Kind, bindErr.Name)
	}
	return err
}
_ = configured

For a workspace placement failure, inspect WorkspacePlacementError.Kind and its optional cause. A canonicalization failure can wrap an OS error; the placement error remains the stable branch. A persistence overlap is a direct topology violation and does not wrap a cause.

%%{init: {"theme":"dark"}}%%
flowchart LR
    A[Definition options] --> B[rig.Define]
    B -- DefinitionError --> C[Fix composition]
    B -- WorkspacePlacementError --> D[Fix root, store, or lease]
    B -- success --> E[loop or hustle Bind]
    E -- BindError or ResolveError --> F[Fix collaborators]
    E -- success --> G[Construct runtime]

Source and runnable proof

Rig definition and lifecycle types are in pkg/rig/errors.go, pkg/rig/workspace_errors.go, and pkg/rig/session_options.go. Loop and hustle definitions are in pkg/loop/definition_errors.go and pkg/hustle/definition_errors.go. Gate, hook, and tool boundaries are defined in pkg/gate/validate.go, pkg/gate/evaluator.go, pkg/hook/errors.go, pkg/tool/definition.go, and pkg/tool/preparation.go. The configuration and workspace error chains are exercised in pkg/rig/rig_test.go, pkg/rig/workspace_test.go, pkg/loop/definition_test.go, and pkg/tool/definition_test.go.