nodestep.exceptions¶

The errors nodestep raises, all derived from NodestepError.

An error keeps its arguments as attributes of the same name. The concept and guide pages, starting at Graphs and flow, say when each one is raised.

Name	What it is
Base error
`NodestepError`	Base class of all nodestep errors.
Graphs and runs
`GraphConfigError`	A graph is configured incorrectly.
`GraphExecutionError`	A graph run failed.
`NodeTimeoutError`	A node exceeded its `timeout`.
`GraphTimeoutError`	A run exceeded the graph `timeout`.
`ResumeError`	A run cannot be resumed as requested.
`RunLimitExceededError`	A run exceeded a limit such as `max_steps`.
`RunInterruptedError`	A run paused for input; resume it with `Resume`.
`ContextNotProvidedError`	A node or tool read `context`, but the run was started without one.
State and stores
`StateUpdateError`	A state update is invalid.
`InvalidUpdateError`	Writes to one field in one superstep cannot be merged.
`StateStoreError`	A state store cannot be used, for example a corrupt file.
`UnknownThreadError`	A thread, or a branch of it, does not exist in the state store.
Chat models
`ModelProviderError`	A call to a chat model failed.
`ChatHistoryError`	The messages sent to a chat model do not form a valid conversation.
`StructuredOutputError`	A model's structured output does not validate against its schema.
`IntegrationNotInstalledError`	An optional dependency of a chat integration is not installed.
Tools
`ToolExecutionError`	A tool call failed.
`ToolGroupExecutionError`	Several parallel tool calls failed.
`ToolDeniedError`	A tool call was denied by a reviewer or a limit.
Sub-agents
`AgentTimeoutError`	Waiting for sub-agents timed out.
`AgentGroupError`	One or more sub-agents in a group failed.
`AgentHandleLostError`	A sub-agent handle is not known where it was looked up.
Workspace
`WorkspaceError`	A workspace operation failed.
`PathAccessError`	A path points outside the workspace root.

Base error¶

NodestepError¶

Base class of all nodestep errors.

Subclass of Exception.

Copying or pickling restores the message and attributes without calling __init__ again.

Graphs and runs¶

GraphConfigError¶

A graph is configured incorrectly.

Subclass of NodestepError.

GraphExecutionError¶

A graph run failed.

Subclass of NodestepError.

NodeTimeoutError¶

NodeTimeoutError(node_name, timeout)

A node exceeded its timeout.

Subclass of GraphExecutionError.

Parameters
`node_name`	`str`	Node that timed out.
`timeout`	`float`	The node's `timeout` in seconds.

GraphTimeoutError¶

GraphTimeoutError(graph_name, timeout)

A run exceeded the graph timeout.

Subclass of GraphExecutionError.

Parameters
`graph_name`	`str`	Name of the graph.
`timeout`	`float`	The graph's `timeout` in seconds.

ResumeError¶

A run cannot be resumed as requested.

Subclass of GraphExecutionError.

RunLimitExceededError¶

RunLimitExceededError(limit_name, limit_value)

A run exceeded a limit such as max_steps.

Subclass of NodestepError.

Parameters
`limit_name`	`str`	Name of the limit, such as `"max_steps"`.
`limit_value`	`int`	Value of the limit.

RunInterruptedError¶

RunInterruptedError(thread_id, interrupts)

A run paused for input; resume it with Resume.

Subclass of NodestepError.

Parameters
`thread_id`	`str \| None`	Thread of the paused run.
`interrupts`	`dict[str, Any]`	Pending interrupts by `Interrupt.key`, as in `GraphResult.interrupts`.

ContextNotProvidedError¶

A node or tool read context, but the run was started without one.

Subclass of NodestepError.

State and stores¶

StateUpdateError¶

A state update is invalid.

Subclass of NodestepError.

InvalidUpdateError¶

InvalidUpdateError(field, nodes, *, replacement=False, superstep=None)

Writes to one field in one superstep cannot be merged.

Subclass of StateUpdateError.

Parameters
`field`	`str`	Field that was written.
`nodes`	`list[str]`	Nodes whose writes conflict.
`replacement`	`bool`	True when the conflict comes from a `Replace` of a field that has a merging reducer.
`superstep`	`Literal['paused', 'unfinished'] \| None`	Set when `update_state` is the other writer: the update was made while the superstep of `nodes` was paused or unfinished.

StateStoreError¶

A state store cannot be used, for example a corrupt file.

Subclass of NodestepError.

UnknownThreadError¶

UnknownThreadError(thread_id, *, branch_id='main')

A thread, or a branch of it, does not exist in the state store.

Subclass of StateStoreError.

Parameters
`thread_id`	`str`	Thread that was requested.
`branch_id`	`str`	Branch that was requested.

Chat models¶

ModelProviderError¶

A call to a chat model failed.

Subclass of NodestepError.

ChatHistoryError¶

The messages sent to a chat model do not form a valid conversation.

Subclass of ModelProviderError.

StructuredOutputError¶

StructuredOutputError(schema_name, message, raw_content=None)

A model's structured output does not validate against its schema.

Subclass of NodestepError.

Parameters
`schema_name`	`str`	Name of the output schema.
`message`	`str`	Validation error reported for the output.
`raw_content`	`str \| None`	Text the model returned.

Attributes
`kind`	`str`	Always `"structured_output_error"`, as on `StructuredOutputEvent`.

IntegrationNotInstalledError¶

IntegrationNotInstalledError(integration, extra)

An optional dependency of a chat integration is not installed.

Subclass of NodestepError and ImportError.

Parameters
`integration`	`str`	Name of the chat integration, such as `"openai"`.
`extra`	`str`	Name of the nodestep extra that installs the dependency.

Tools¶

ToolExecutionError¶

ToolExecutionError(tool_name, input_data, message)

A tool call failed.

Subclass of NodestepError.

Parameters
`tool_name`	`str`	Tool that was called.
`input_data`	`Any`	Arguments of the call.
`message`	`str`	Why the call failed; it goes into the error text, not into an attribute.

ToolGroupExecutionError¶

ToolGroupExecutionError(errors)

Several parallel tool calls failed.

Subclass of NodestepError.

Parameters
`errors`	`list[BaseException]`	The error of each failed call.

ToolDeniedError¶

ToolDeniedError(tool_name, reason=None)

A tool call was denied by a reviewer or a limit.

Subclass of NodestepError.

Parameters
`tool_name`	`str`	Tool whose call was denied.
`reason`	`str \| None`	Why it was denied, such as the reviewer's message or the limit.

Sub-agents¶

AgentTimeoutError¶

AgentTimeoutError(completed, pending)

Waiting for sub-agents timed out.

Subclass of NodestepError.

Parameters
`completed`	`list[AgentResult]`	Results of the sub-agents that finished in time.
`pending`	`list[AgentHandle]`	Handles of the sub-agents that did not finish; they were cancelled.

AgentGroupError¶

AgentGroupError(results)

One or more sub-agents in a group failed.

Subclass of NodestepError.

Parameters
`results`	`list[AgentResult]`	Results of every sub-agent in the group, failed or not.

AgentHandleLostError¶

AgentHandleLostError(handle_id, reason)

A sub-agent handle is not known where it was looked up.

Subclass of NodestepError.

Parameters
`handle_id`	`str`	The id that was looked up.
`reason`	`str`	Why the id is not known there.

Workspace¶

WorkspaceError¶

A workspace operation failed.

Subclass of NodestepError.

PathAccessError¶

A path points outside the workspace root.

Subclass of WorkspaceError.