# 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

| Error | Meaning |
| --- | --- |
| `ContextPromptTooLarge` | Provider-facing prompt text exceeds its byte budget. |
| `ContextToolsTooLarge` | Tool definitions or tool traffic exceed their byte budget. |
| `ContextSchemaTooLarge` | Tool or output schemas exceed their byte budget. |
| `ContextMediaTooLarge` | Rich-media sources exceed their raw byte budget. |
| `ContextTokenLimitExceeded` | Estimated input exceeds total capacity after output reservation. |
| `ContextSizeOverflow` | Aggregate context size cannot be represented as `u64`. |
| `InputTokenLimitExceeded` | Provider-reported cumulative input usage exceeded the run limit. |
| `OutputTokenLimitExceeded` | Provider-reported cumulative output usage exceeded the run limit. |
| `TotalTokenLimitExceeded` | Provider-reported combined usage exceeded the run limit. |
| `CostLimitExceeded` | Available provider-reported or estimated cost exceeded the nano-USD run limit. |
| `UsageOverflow` | A usage counter, duration, or exact cost exceeded its integer representation. |
| `MaxModelRequestsExceeded` | The run exhausted its model-request budget. |
| `MaxToolCallsExceeded` | The run exhausted its local tool-call budget. |

### Model capabilities and output

| Error | Meaning |
| --- | --- |
| `ModelDoesNotSupportAudio` | Audio was supplied to a model profile without audio support. |
| `ModelDoesNotSupportBinaryContent` | Generic binary content is unsupported. |
| `ModelDoesNotSupportDocuments` | Documents are unsupported. |
| `ModelDoesNotSupportImages` | Images are unsupported. |
| `ModelDoesNotSupportSystemMessages` | System prompts or instructions are unsupported. |
| `ModelDoesNotSupportThinking` | Thinking content cannot be preserved. |
| `ModelDoesNotSupportTools` | Local tools are unsupported. |
| `ModelDoesNotSupportVideo` | Video was supplied to a model profile without video support. |
| `ModelDoesNotSupportWebFetch` | Native web fetch is unsupported. |
| `ModelDoesNotSupportWebSearch` | Native web search is unsupported. |
| `ModelDoesNotSupportXSearch` | Native X search is unsupported. |
| `ModelDoesNotSupportCodeExecution` | Provider-managed code execution is unsupported. |
| `ModelDoesNotSupportFileSearch` | Provider-managed file search is unsupported. |
| `ModelDoesNotSupportRemoteMcp` | Provider-managed remote MCP is unsupported. |
| `ModelDoesNotSupportJsonObjectOutput` | JSON-object output is unsupported. |
| `ModelDoesNotSupportJsonSchemaOutput` | JSON Schema output is unsupported. |
| `ModelDoesNotSupportMaxTokens` | The model rejects `max_tokens`. |
| `ModelDoesNotSupportReasoningEffort` | The requested reasoning effort is unsupported. |
| `ModelDoesNotSupportSeed` | The model rejects deterministic seeds. |
| `ModelDoesNotSupportStopSequences` | The model rejects stop sequences. |
| `ModelDoesNotSupportStreaming` | The selected model cannot stream. |
| `ModelDoesNotSupportTemperature` | The model rejects temperature. |
| `ModelDoesNotSupportTopP` / `ModelDoesNotSupportTopK` | The requested sampling control is unsupported. |
| `ModelDoesNotSupportPresencePenalty` / `ModelDoesNotSupportFrequencyPenalty` | The requested penalty is unsupported. |
| `ModelDoesNotSupportLogprobs` | The model cannot return requested log probabilities. |
| `ModelDoesNotSupportToolChoice` | The model cannot encode the requested tool-choice policy. |
| `ModelDoesNotSupportParallelToolCallSetting` | The provider cannot encode an explicit parallel-tool policy. |
| `ModelDoesNotSupportThinkingBudget` | The model cannot accept a thinking token budget. |
| `ModelDoesNotSupportServiceTier` | The requested service tier is absent from the profile. |
| `ModelDoesNotSupportTruncation` | The model cannot encode truncation policy. |
| `ModelDoesNotSupportRequestHeaders` | The model does not expose request-scoped headers. |
| `ModelDoesNotSupportExtraBody` | The provider-extension tag does not match the model profile. |
| `InvalidModelSettings` | A portable value, tool selector, or request header is malformed. |
| `ContentFiltered` | Provider filtering ended generation. |
| `EmptyModelResponse` | A successful response had no usable parts. |
| `IncompleteToolCall` | Generation ended inside a tool call. |
| `ModelOutputTruncated` | Length termination prevented a complete result. |
| `InvalidTypedOutput` | Validated structured output could not decode as the requested Zig type. |
| `InvalidStructuredOutput` | Structured output could not decode for the final stream snapshot. |
| `InvalidOutputSpec` | An output name, schema, alternative list, or prompt template is malformed. |
| `ModelDoesNotSupportPromptedOutput` | Prompted output was selected for a model without instruction support. |
| `OutputToolRequired` | Tool-output mode received no output-tool call before its retry budget ended. |
| `OutputRetriesExceeded` | An output function or validator requested another attempt after its retry budget ended. |
| `ProviderFileProviderMismatch` | A provider-managed file belongs to another provider. |
| `PendingMessageQueueAlreadyUsed` | A one-run pending-message queue was attached again. |
| `PendingMessageQueueClosed` | A message was submitted after the queue stopped accepting input. |

### Tools and deferred runs

| Error | Meaning |
| --- | --- |
| `DuplicateToolName` | Two local tools have the same provider-visible name. |
| `DuplicateBuiltinTool` | A provider-managed tool identity was registered twice. |
| `DuplicateCapabilityId` | Two composed capability scopes declare the same stable ID. |
| `InvalidCapability` | A capability ID, metadata list, dependency, conflict, limit, or active-state declaration is invalid. |
| `MissingCapabilityDependency` | A dependency ID is absent from the composed capability registry. |
| `CapabilityDependencyCycle` | Capability dependencies contain a cycle. |
| `CapabilityConflict` | Initial capability composition would activate two conflicting bundles. |
| `UnknownTool` | The model requested a tool unavailable in the current step. |
| `ParallelToolCallsNotSupported` | The model emitted parallel calls while policy disabled them. |
| `ParallelToolCallsRequireIo` | Parallel execution requires an `Io` runtime. |
| `ToolConcurrencyUnavailable` | The runtime cannot schedule the controlled tool tasks. |
| `ToolIsolationRequiresIo` | A timeout or concurrency control requires `Io`. |
| `ToolQueueOverflow` | Too many tool calls are waiting for a slot. |
| `ToolResultTooLarge` | Encoded tool output exceeds its byte limit. |
| `ToolFollowUpOverflow` | Tool follow-up count or aggregate bytes exceed policy. |
| `ToolTimedOut` | A local tool exceeded its timeout. |
| `ToolCallRequiresDeferredRun` | A normal run encountered approval or external execution. |
| `MissingDeferredToolDecision` | A paused call has no resume decision. |
| `UnexpectedDeferredToolDecision` | A decision does not match a paused call. |
| `DeferredToolRequiresResult` | External execution resumed without a result. |
| `InvalidDeferredState` | Paused state or resume JSON is malformed or incompatible. |
| `InvalidContentRole` | A follow-up part is invalid for a request message. |
| `InvalidToolFollowUpMessage` | A follow-up violates provider message invariants. |

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

| Error | Meaning |
| --- | --- |
| `Cancelled` | The run's cancellation token was signalled. |
| `RunTimedOut` | The invocation deadline elapsed. |
| `RunControlRequiresIo` | A deadline was configured without `Io`. |
| `RunControlConcurrencyUnavailable` | The runtime cannot schedule an operation and its watchers. |
| `RetryBackoffRequiresIo` | Retry sleep was configured without `Io`. |
| `RetryIdempotencyRequiresIo` | Idempotent retry keys need an `Io` entropy source. |

### Security policy

| Error | Meaning |
| --- | --- |
| `InvalidUrl` | An outbound or provider-fetched value is not a valid absolute URL. |
| `UrlMissingHost` | The URL has no network host. |
| `UrlSchemeNotAllowed` | The URL is not HTTPS and HTTP was not enabled. |
| `UrlCredentialsForbidden` | The URL embeds a username or password. |
| `LocalNetworkUrlForbidden` | The URL uses a local name or non-public literal IP. |
| `UrlHostNotAllowed` | The URL host is absent from an explicit allowlist. |
| `UrlOriginNotAllowed` | A provider-directed URL does not match the configured API origin. |

### MCP authorization

| Error | Meaning |
| --- | --- |
| `InvalidAuthorizationIssuer` | A token, response, or metadata document is bound to a different authorization-server issuer. |
| `MissingAuthorizationIssuer` | RFC 9207 support was advertised but the authorization response omitted `iss`. |
| `InvalidAuthorizationServerMetadata` | Discovered OAuth/OIDC metadata is missing required fields or contains an ineligible endpoint. |
| `InvalidProtectedResourceMetadata` | RFC 9728 metadata is malformed, mismatched, duplicated, or lacks Bearer-header support. |
| `InvalidResourceUri` | The configured RFC 8707 resource is not an eligible canonical endpoint URI. |
| `PkceUnsupported` | Authorization-server metadata does not advertise `S256`. |
| `InvalidBearerChallenge` | A `WWW-Authenticate` Bearer challenge is malformed or ambiguous. |
| `InvalidBearerToken` | A token is empty, unsafe for an HTTP header, malformed, or conflicts with a configured token provider. |
| `InvalidOrigin` | A present browser Origin is malformed, duplicated, or outside the exact allowlist. |
| `InvalidRequestHost` | A required Host is absent, malformed, duplicated, or does not match deployment policy. |
| `InsecureHttpTransport` | A protected server request arrived over cleartext without an explicit development opt-in. |

## Provider errors

All adapters use the stable `ProviderRequestError` categories.

| Error | Meaning | Retried by default |
| --- | --- | --- |
| `ProviderConnectionError` | A recognized DNS, connect, or connection-lifetime failure. | Yes |
| `ProviderResponseDecodeError` | A success payload cannot be decoded. | Yes |
| `ProviderRateLimited` | HTTP 429. | Yes |
| `ProviderServerError` | HTTP 5xx. | Yes |
| `ProviderRequestFailed` | Another non-success status. | No |

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:

| Namespace | Error | Meaning |
| --- | --- | --- |
| `provider` | `InvalidProviderPolicy` | Identity, API root, timeout, or URL policy is invalid. |
| `provider` | `UnsupportedProviderOperation` | The provider does not implement the requested discovery or file operation. |
| `provider` | `InvalidProviderFileInput` | Upload metadata is empty, oversized, unsafe for multipart framing, or unsupported by the provider. |
| `provider` | `ProviderFileTooLarge` | Upload bytes exceed the configured provider file limit. |
| `provider` | `InvalidProviderFileOwner` | A file handle or returned descriptor belongs to another provider. |
| `provider` | `InvalidProviderFileReference` | A file handle is empty, or an operation returned metadata for another file ID. |
| `providers.http` | `InvalidProviderCredential` | A credential is empty or unsafe for an HTTP header. |
| `providers.http` | `InvalidProviderEndpoint` | The API root or adapter endpoint is ambiguous or not relative. |
| `providers.http` | `InvalidProviderHeader` | A configured or adapter header is malformed. |
| `providers.http` | `ProviderHeaderConflict` | Two layers claim the same case-insensitive header name. |

## Transport and data errors

| Namespace | Error | Meaning |
| --- | --- | --- |
| `transport` | `ResponseTooLarge` | A decompressed buffered body exceeded policy. |
| `transport` | `StreamLineTooLarge` | A decompressed stream line exceeded policy. |
| `transport` | `RequestCancelled` | Cancellation interrupted transport work. |
| `transport` | `RequestTimedOut` | The transport deadline elapsed. |
| `transport` | `StreamingNotSupported` | The transport has no line-streaming implementation. |
| `transport` | `UnsupportedCompressionMethod` | The response encoding cannot be decompressed. |
| `transport` | `RedirectRejected` | A 3xx response was rejected without following its target. |
| `json` | `DocumentTooLarge` | Encoded JSON exceeds its boundary limit. |
| `json` | `ValueTooLarge` | One decoded string or encoded number is too large. |
| `json` | `NestingTooDeep` | JSON nesting exceeds policy. |
| `json` | `CollectionTooLarge` | One object or array has too many entries. |
| `json` | `InvalidJson` | Input is not one complete JSON document. |
| `json_schema` | `InvalidJsonOutput` | Structured output is not valid JSON. |
| `json_schema` | `InvalidJsonSchema` | The configured schema is invalid. |
| `json_schema` | `UnsupportedJsonSchema` | The schema uses vocabulary outside ZigAI's documented fail-closed subset. |
| `json_schema` | `OutputSchemaValidationFailed` | Output does not satisfy the schema. |
| `history` | `InvalidHistory` | History JSON or message sequence is invalid. |
| `history` | `UnsupportedVersion` | The history version is unsupported. |
| `codecs.pydantic_ai` | `InvalidMessages` | Valid JSON does not have the PydanticAI stable-v2 message shape. |
| `messages.ProviderDetails.fromValue` | `InvalidProviderDetails` | Provider details are not a JSON object. |
| `context_budget` | `ContextSizeOverflow` | Byte or estimate arithmetic overflowed. |
| `evals` | `MissingExpectedOutput` | An evaluator requires an absent expected value. |
| `evals` | `InvalidModelGrade` | A model grader returned an invalid grade. |

### Agent specification errors

| Error | Meaning |
| --- | --- |
| `InvalidAgentSpec` | JSON/YAML shape, identifier, value, duplicate, or bound is invalid. |
| `UnsupportedAgentSpecVersion` | The document version is not supported. |
| `InvalidEnvironmentInterpolation` | A placeholder is malformed. |
| `EnvironmentVariableNotAllowed` | A secret reference or placeholder is outside its explicit allowlist. |
| `MissingEnvironmentVariable` | An allowed environment value is unavailable. |
| `EmptySecret` | An allowed secret variable exists but is empty. |
| `UnknownProvider` / `UnknownModel` | The application resolver does not recognize the selection. |
| `InvalidProviderConfiguration` | The resolver rejects the expanded endpoint or provider fields. |
| `UnknownCapability` | No implementation exists for a declared capability or dependency. |
| `InvalidCapabilityImplementation` | A catalog entry is anonymous or returns a different ID. |
| `InvalidCapabilityComposition` | The resolved registry has a structural, dependency, cycle, or conflict diagnostic. |

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

## MCP errors

| Error | Meaning |
| --- | --- |
| `EmptyCommand` | A stdio transport has no program command. |
| `HeaderMismatch` | A header value violates its schema annotation. |
| `InputRequired` | Elicitation needs input but no handler supplied it. |
| `InvalidMcpHeaderAnnotation` | Tool header annotations are malformed. |
| `InvalidMcpMessage` | A JSON-RPC message is malformed. |
| `InvalidMcpResponse` | A result does not match its method shape. |
| `InvalidMcpToolArguments` | Tool arguments are not a bounded JSON object. |
| `InvalidMcpTransportConfiguration` | An MCP transport concurrency or buffering limit is invalid. |
| `InvalidTaskStore` | A durable task snapshot is malformed or has an unsupported version. |
| `McpHttpRequestFailed` | Streamable HTTP returned a non-success response. |
| `McpMessageTooLarge` | An MCP message exceeded its byte limit. |
| `McpPaginationCursorCycle` | A paginated collection repeated a cursor. |
| `McpProcessClosed` | A stdio child closed before the matching response. |
| `McpResponseIdMismatch` | A response ID does not match the request. |
| `McpRpcError` | The peer returned a JSON-RPC error envelope. |
| `McpStdioBackpressure` | A stdio transport reached its pending-request bound. |
| `MissingMcpClient` | An MCP toolset has no client. |
| `MissingMcpClientCapability` | A Tasks operation was attempted without the extension capability. |
| `MissingMcpTaskStore` | Durable task resumption was requested without a store. |
| `MissingMcpSseResponse` | Streamable HTTP did not produce the required SSE stream. |
| `SubscriptionRecoveryRequiresIo` | A nonzero subscription recovery delay has no I/O runtime. |
| `TaskPollingRequiresIo` | A nonzero task polling delay has no I/O runtime. |
| `TaskStoreTooLarge` | A durable task snapshot exceeded its configured byte bound. |
| `TooManyMcpPages` | Tool discovery exceeded the configured page limit. |
| `TooManyMcpRoundTrips` | Elicitation exceeded its round-trip limit. |
| `TooManyMcpTaskPolls` | A task remained non-terminal after its bounded polling budget. |
| `UnsupportedMcpProtocolVersion` | Discovery negotiated an unsupported revision. |

## Application errors

Tool functions, lifecycle hooks, stream sinks, dynamic instructions, history
processors, selectors, evaluators, transports, telemetry exporters, 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:

| Callback | Contract | Reason |
| --- | --- | --- |
| Provider error observer | Infallible | Observation cannot change request control flow. |
| Token estimator | Infallible | It performs borrowed, allocation-free counting. |
| Tool recovery classifier | Infallible | It classifies an error already produced. |
| Tool, model, and transport operations | Fallible | They perform application or external I/O work. |
| Stream, lifecycle, retry, and telemetry sinks | Fallible | Applications may stop a run when delivery fails. |
| Instructions, history, toolsets, selectors, and evaluators | Fallible | They may allocate or call application services. |
| MCP handlers and event sinks | Fallible | They cross application and protocol boundaries. |

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.