@nhtio/adk/exceptions

Core ADK exception classes and reusable runtime error constructors.

Every exception has a stable E_* code. The fatal flag on each code controls whether it throws synchronously (programming error — no recovery path) or is emitted on the observability error bus (runtime failure — run() still resolves).

Classes

Class	Description
ValidationException	Thrown when input fails schema validation.

Artifacts

Exceptions from spool and media artifact construction. Fatal — wrap-site validation that the supplied value implements the required reader interface.

Variable	Description
E_INVALID_INITIAL_MEDIA_VALUE	Thrown when a Media is initialised with a value that fails schema validation.
E_NOT_A_MEDIA_READER	Thrown when a Media is constructed with a value that does not implement the MediaReader interface.
E_NOT_A_SPOOL_READER	Thrown when a @nhtio/adk!SpooledArtifact is constructed with a value that does not implement the @nhtio/adk!SpoolReader interface.

Dispatch

Exceptions from the dispatch loop and its executor. A mix of fatal (programming errors) and non-fatal (runtime failures that nack the dispatch). The loop terminates as 'ack', 'nack', or 'aborted' — inspect dispatchEnd.status to classify.

Variable	Description
E_INVALID_LLM_DISPATCH_INPUT	Thrown when @nhtio/adk!DispatchRunner.dispatch receives an input that fails schema validation.
E_INVALID_LLM_EXECUTION_CONTEXT	Thrown when @nhtio/adk!DispatchContext is constructed with a value that fails schema validation.
E_LLM_EXECUTION_ALREADY_SIGNALLED	Thrown when @nhtio/adk!DispatchContext.ack or @nhtio/adk!DispatchContext.nack is called on a context that has already been signalled.
E_LLM_EXECUTION_EXECUTOR_ERROR	Emitted (via the observability error hook) and re-thrown when the user-supplied executor callback throws during @nhtio/adk!DispatchRunner.dispatch.
E_LLM_EXECUTION_GATE_NOT_SUPPORTED	Thrown (as a rejection reason) when @nhtio/adk!DispatchContext.waitFor is called on a standalone context that was constructed without a waitFor function.

Gates

Exceptions from @nhtio/adk!TurnGate construction and settlement. All four settlement outcomes (resolved, invalid-resolution, aborted, timed-out) also emit turnGateClosed on the observability bus.

Variable	Description
E_INVALID_INITIAL_TURN_GATE_VALUE	Thrown when a @nhtio/adk!TurnGate is constructed with a value that fails schema validation.
E_INVALID_TURN_GATE_RESOLUTION	Thrown synchronously in the caller's context when @nhtio/adk!TurnGate.resolve is called with a value that fails the gate's schema.
E_TURN_GATE_ABORTED	Thrown (as a rejection reason) when a @nhtio/adk!TurnGate is aborted — either because the turn's AbortSignal fired or because @nhtio/adk!TurnGate.abort was called directly.
E_TURN_GATE_TIMEOUT	Thrown (as a rejection reason) when a @nhtio/adk!TurnGate times out before being resolved.

Pipelines

Non-fatal pipeline errors emitted on the observability error bus when middleware throws or a pipeline short-circuits. run() resolves; turnEnd still fires.

Variable	Description
E_DISPATCH_PIPELINE_ERROR	Emitted (via the observability error hook) and re-thrown when a non-abort error propagates out of the input or output middleware pipeline during @nhtio/adk!DispatchRunner.dispatch.
E_INPUT_PIPELINE_ERROR	Emitted (via the error event) when a non-abort error propagates out of the input middleware pipeline during @nhtio/adk!TurnRunner.run.
E_OUTPUT_PIPELINE_ERROR	Emitted (via the error event) when a non-abort error propagates out of the output middleware pipeline during @nhtio/adk!TurnRunner.run.
E_PIPELINE_SHORT_CIRCUITED	Emitted (via the error event) when a middleware pipeline resolves without reaching its terminal handler and without the turn being aborted. Indicates that some middleware returned without calling next and without signalling a deliberate refusal via the turn's abort controller.

Primitive Validation

Fatal exceptions thrown at construction time when a primitive (@nhtio/adk!Message, @nhtio/adk!Memory, @nhtio/adk!Thought, @nhtio/adk!ToolCall, @nhtio/adk!Retrievable, @nhtio/adk!Identity, @nhtio/adk!Registry) receives an invalid initial value. If a primitive constructed, it is valid.

Variable	Description
E_INVALID_INITIAL_IDENTITY_VALUE	Thrown when an @nhtio/adk!Identity is initialised with a value that fails schema validation.
E_INVALID_INITIAL_MEMORY_VALUE	Thrown when a @nhtio/adk!Memory is initialised with a value that fails schema validation.
E_INVALID_INITIAL_MESSAGE_VALUE	Thrown when a @nhtio/adk!Message is initialised with a value that fails schema validation.
E_INVALID_INITIAL_REGISTRY_VALUE	Thrown when a registry is initialised with a value that is defined but not a plain object.
E_INVALID_INITIAL_RETRIEVABLE_VALUE	Thrown when a @nhtio/adk!Retrievable is initialised with a value that fails schema validation.
E_INVALID_INITIAL_THOUGHT_VALUE	Thrown when a @nhtio/adk!Thought is initialised with a value that fails schema validation.
E_INVALID_INITIAL_TOOL_CALL_VALUE	Thrown when a @nhtio/adk!ToolCall is initialised with a value that fails schema validation.

Tools

Exceptions from tool construction, registration, argument validation, and handler execution. E_TOOL_DOWNSTREAM_ERROR wraps handler throws — the original error is on .cause.

Variable	Description
E_INVALID_INITIAL_TOOL_VALUE	Thrown when a @nhtio/adk!Tool is constructed with a value that fails schema validation.
E_INVALID_TOOL_ARGS	Thrown synchronously when @nhtio/adk!Tool.validate is called with arguments that fail the tool's input schema.
E_TOOL_ALREADY_REGISTERED	Thrown when @nhtio/adk!ToolRegistry.register is called for a tool name that is already registered and overwrite is not true.
E_TOOL_DOWNSTREAM_ERROR	Thrown (as a rejection reason) when a @nhtio/adk!Tool's handler throws during execution.

Turn Input Validation

Exceptions thrown when the raw turn context supplied to runner.run() fails validation. Fatal and synchronous — thrown before turnStart is emitted.

Variable	Description
E_INVALID_TURN_CONTEXT	Thrown by @nhtio/adk!TurnRunner when the @nhtio/adk!TurnContext supplied to run fails schema validation.

Turn Runner Construction

Exceptions thrown when a @nhtio/adk!TurnRunner is misconfigured at construction time. Fatal — a misconfigured runner cannot execute turns.

Variable	Description
E_INVALID_TURN_RUNNER_CONFIG	Thrown by @nhtio/adk!TurnRunner when the supplied config object fails schema validation at construction time.