Error reference¶

ZigAI returns named errors for framework decisions and preserves allocator, runtime, transport implementation, and application callback errors alongside them. Public operations therefore use inferred error unions: handle the named cases relevant to the application, then propagate the remainder.

Agent errors¶

Context and usage¶

Model capabilities and output¶

Tools and deferred runs¶

On-demand load failures such as UnknownCapability, CapabilityAlreadyAvailable, InvalidCapabilityArguments, and a dynamic CapabilityConflict are ordinary recoverable tool failures. They are returned to the model from load_capability; they do not escape as an agent setup error or partially activate a bundle.

Runtime control¶

Security policy¶

MCP authorization¶

Provider errors¶

All adapters use the stable ProviderRequestError categories.

Adapters additionally expose InvalidProviderResponse for direct decoder calls and InvalidRequestEncoding for unrepresentable input. OpenAI adds UnsupportedBuiltinTool and UnsupportedContentType. Anthropic adds UnsupportedContentType and UnsupportedOutputMode. Google adds UnsupportedContentType.

ProviderErrorObserver is infallible and synchronous. Its values are borrowed. Raw bodies are empty unless ProviderErrorPolicy.capture_body is enabled, and even then they cannot exceed max_body_bytes. Configured API keys are always suppressed; sensitive_data_redacted reports when this changed visible detail.

Provider construction and optional operations use these boundary errors:

Transport and data errors¶

Agent specification errors¶

ProviderResolver.buildFn is an application extension point. Its allocation, client-construction, and application errors propagate unchanged. Dry-run validation never invokes it.

Durable execution errors¶

Graph errors¶

Graph snapshot operations additionally report:

Graph.renderMermaid returns VisualizationLimitExceeded when its title or encoded document exceeds the configured visualization bound, and preserves OutOfMemory for allocator failures.

Graph agent nodes preserve OutOfMemory and Cancelled. Every other agent failure maps to StepFailed at the graph boundary. A configured graph_agent.Observer receives the original error name and the prepare, agent, stream, or apply failure phase synchronously before the graph latches that error. A correlation/durable run-ID mismatch and deadline without an available std.Io runtime map to StepFailed before provider work. A stream sink may return only the graph callback errors; its failure prevents result adaptation and transition commit.

Multi-agent errors¶

Target agent failures keep their original error. The session emits a borrowed failure event with the transition identity. Cancellation and deadline errors therefore remain Cancelled, RunTimedOut, or RunControlRequiresIo rather than becoming a multi-agent wrapper error.

Embedding errors¶

Provider, cancellation, deadline, callback, and allocator failures preserve their original error. Validation failures happen before provider I/O. A failed later batch releases all vectors copied from earlier batches.

Realtime errors¶

Realtime validation reports InvalidRealtimeLimits, InvalidRealtimeContent, InvalidRealtimeAudio, InvalidRealtimeToolCall, or RealtimeContentTooLarge before provider side effects. Profile-gated methods return UnsupportedRealtimeOperation; non-byte images return UnsupportedRealtimeContent; a missing tool dispatcher returns UnknownRealtimeTool.

RealtimeSessionClosed rejects every operation after close. RealtimeHistoryLimitExceeded and RealtimeUsageLimitExceeded latch bounded history and token growth. RealtimeReconnectRequiresIo rejects delayed redial without a runtime, while RealtimeReconnectExhausted means the per-drop or session recovery budget ended. Unclassified provider and callback failures keep their original error.

Browser UI errors¶

UI adapters report InvalidUIIdentifier, InvalidUIMessage, InvalidUICustomEvent, and InvalidUIApproval for malformed trusted boundaries. UntrustedUIMessageRole prevents browser-controlled system, tool, activity, or reasoning messages from entering canonical agent history. TooManyUIMessages and UIContentTooLarge enforce collection and byte limits. UISequenceExhausted prevents replay cursor wraparound. Encoder, sink, replay, and allocator failures retain their original error.

Agent harness errors¶

InvalidHarnessLimits and InvalidHarnessCapability reject malformed compositions before an agent run. HarnessOutputTooLarge, TooManyHarnessArtifacts, HarnessArtifactTooLarge, and InvalidHarnessArtifact bound every retained result. Agent, producer, observer, cancellation, deadline, and allocator failures keep their original errors.

Execution environment errors¶

InvalidExecutionPath, InvalidExecutionCommand, and InvalidExecutionEnvironment reject malformed requests before I/O. ReadOnlyWorkspace, ExecutionFileTooLarge, ExecutionCommandDenied, ExecutionNetworkDenied, NetworkIsolationUnavailable, SensitiveEnvironmentDenied, and TooManyExecutionEnvironmentVariables identify policy failures. WorkspaceNotDisposable rejects disposal through a borrowed environment. Process, cancellation, deadline, output-limit, audit, and allocator failures retain their original errors.

Built-in capability errors¶

InvalidBuiltinCapabilityArguments, BuiltinCapabilityOutputTooLarge, and InvalidGeneratedImage reject malformed or oversized local capability data. Browser URL failures preserve the shared security taxonomy. Repository filesystem/root failures preserve execution-environment errors. Optional backend and allocator failures retain their original errors.

Durable memory errors¶

InvalidMemoryIdentifier, InvalidMemoryEntry, InvalidMemoryQuery, and InvalidMemoryEmbedding reject malformed tenant, record, query, or vector data. MemoryEntryTooLarge, MemoryEntryAlreadyExists, and MemoryStoreFull identify bounded storage failures. Compactor, persistent-store, cosine, and allocator errors preserve their original categories.

Planning errors¶

InvalidPlan, PlanRevisionExhausted, TooManyPlanAdvisors, PlanAdviceTooLarge, PlanStepOutputTooLarge, PlanApprovalDenied, and PlanApprovalRequired identify structural, bounded, and approval failures. Advisor, executor, nested-agent, observer, usage, cancellation, deadline, and allocator errors retain their original categories.

Runtime service errors¶

Step stores report InvalidStepRecord, StepRevisionConflict, InvalidRuntimePayload, and RuntimePayloadTooLarge. Blob/prompt stores report InvalidBlob, BlobAlreadyExists, BlobStoreFull, InvalidManagedPrompt, ManagedPromptAlreadyExists, and ManagedPromptStoreFull. Prompt rendering adds MissingPromptVariable and ManagedPromptTooLarge. Executors report InvalidExecutorLimits, ExecutorConcurrencyUnavailable, and ExecutorOutputTooLarge. Backend, callback, cancellation, deadline, and allocator errors remain unchanged.

ACP errors¶

InvalidACPState, ACPNotInitialized, ACPSessionRequired, UnsupportedACPVersion, UnsupportedACPCapability, InvalidACPMessage, InvalidACPPrompt, InvalidACPPath, and ACPPathOutsideRoot reject protocol or lifecycle misuse. InvalidACPPermissionDecision and UnsupportedACPClientMethod fail closed on agent-to-client requests. ACPRequestCancelled, ACPRemoteError, ACPRequestIdExhausted, ACPProcessClosed, ACPMessageTooLarge, and ACPReconnectExhausted preserve transport/runtime distinctions. Handler, execution, cancellation, deadline, and allocator failures remain unchanged.

Production CLI errors¶

InvalidArguments, InvalidCLIConfig, InvalidPausedCLIState, EmptyPrompt, MissingApiKey, and ApprovalDecisionRequired identify operator-correctable failures without exposing credential values. Provider errors retain their stable categories. The process maps them to the documented 0, 1, 2, 3, 4, 5, and 10 exit statuses instead of relying on platform-specific panic or error-return behavior.

MCP errors¶

Application errors¶

Tool functions, lifecycle hooks, stream sinks, dynamic instructions, history processors, selectors, evaluators, transports, telemetry exporters, diagnostic sinks, and MCP handlers may return application-defined errors. ZigAI propagates them unchanged. They are intentionally not converted to ProviderConnectionError or another framework category.

The public callback contracts are split deliberately:

This keeps anyerror only at extension points where preserving the application's concrete error is part of the API. Framework-owned decisions use the named sets above.