Public errors

July 31, 2026 · View on GitHub

This reference covers the stable error identities owned by the root adaptor package and the public leaf packages that define Driver, Tool, skill, MCP, Thread storage, A2A client, and hosttool contracts.

Use errors.Is for a category and errors.As when the table names a typed error. Error strings are diagnostics, not matching contracts.

One execution error path

Runner.Run and Stream.Result use one verdict model:

success returns *Result, nil;
a completed business failure returns *RunError, whose Result retains the available audit data;
configuration, context, process, protocol, store, and resource failures are ordinary wrapped errors.

result, err := runner.Run(ctx, prompt)
if err != nil {
	var runErr *adaptor.RunError
	if errors.As(err, &runErr) {
		result = runErr.Result
		log.Printf("business failure %s: %s", runErr.Reason, runErr.Message)
		return err
	}
	return err
}
_ = result

Stream itself returns immediately; setup and execution failures are read from Stream.Result() after its event channel closes. Programmer-contract violations documented as panics, such as constructing an Agent with a nil Driver or creating a Thread with an empty key, are not error sentinels.

Agent lifecycle

ErrAgentClosed means Agent.Close has started. New Run/Stream calls on the Agent or any Thread derived from it fail with this sentinel and do not restart the Driver's process pool. Close itself is idempotent; its context error reports a bounded cleanup failure rather than changing this sentinel.

Root business failures

Every row is a *adaptor.RunError. errors.As exposes Reason, Message, Details, and the non-nil Result; errors.Is selects one category.

Sentinel	`FailureReason`	Meaning
`ErrApprovalDenied`	`ReasonApprovalDenied`	A host or auto policy denied an approval and the fallback aborted.
`ErrApprovalTimeout`	`ReasonApprovalTimeout`	An approval deadline elapsed and the fallback aborted.
`ErrAgentFailed`	`ReasonAgentError`	The Driver classified an agent-level failure, such as a bad terminal protocol or non-zero exit.
`ErrRunCancelled`	`ReasonCancelled`	The Driver returned a classified cancellation business failure.
`ErrPolicyViolation`	`ReasonPolicyViolation`	A completed invocation violated a run policy, including default fail-on-invalid structured output.

context.Canceled and context.DeadlineExceeded are infrastructure errors; they do not imply ErrRunCancelled. Likewise, malformed host policy values match ErrInvalidPolicy, not ErrPolicyViolation.

Unknown Driver failure codes remain available as RunError.Reason but do not silently match one of the five sentinels above.

Root pre-invocation errors

These failures occur before Driver.Run is invoked. The root variables are the exact same identities as their owner-package variables.

Root sentinel	Canonical leaf identity	Typed error for `errors.As`	Meaning
`ErrSkillNotFound`	`skill.ErrSkillNotFound`	—	A requested catalogue key was not resolved.
`ErrSkillKeyConflict`	`skill.ErrSkillKeyConflict`	`*adaptor.SkillKeyConflictError` (`Key`, `Sources`, `Detail`)	Structurally different skill declarations use the same key.
`ErrSkillMaterializationFailed`	`skill.ErrSkillMaterializationFailed`	`*adaptor.SkillMaterializationError` (`Key`, `RuntimeName`, `Cause`)	A resolved skill could not be staged for the Driver.
`ErrSkillSourceMissing`	`skill.ErrSkillSourceMissing`	—	A concrete skill has no source.
`ErrSkillKeyMissing`	`skill.ErrSkillKeyMissing`	—	A concrete skill has an empty key.
`ErrInvalidMCPConfig`	`mcp.ErrInvalidConfig`	—	An MCP declaration has a missing/duplicate key, missing command/URL, unknown transport, or transport-field mismatch.
`ErrMCPUnsupported`	`mcp.ErrUnsupported`	—	The Driver declares no MCP support.
`ErrMCPTransportUnsupported`	`mcp.ErrTransportUnsupported`	—	The Driver does not support the requested MCP transport.
`ErrInvalidOutputSchema`	`driver.ErrInvalidOutputSchema`	`*adaptor.InvalidOutputSchemaError` (`Reason`, `Cause`)	A schema cannot be derived, parsed, normalized, or compiled.
`ErrStructuredOutputUnsupported`	`driver.ErrStructuredOutputUnsupported`	`*adaptor.StructuredOutputUnsupportedError` (`Driver`, `Reason`)	Neither native enforcement nor Prompt plus local validation can honor the request.
`ErrInvalidDriverConfig`	`driver.ErrInvalidDriverConfig`	`*adaptor.InvalidDriverConfigError` (`Driver`, `Cause`)	`Driver.ValidateConfig` rejected the captured configuration.
`ErrInvalidPolicy`	`driver.ErrInvalidPolicy`	`*adaptor.InvalidPolicyError` (`Driver`, `Field`, `Value`)	A policy enum, action, or retry value is out of domain.
`ErrPolicyCapabilityUnsupported`	`driver.ErrPolicyCapabilityUnsupported`	`*adaptor.PolicyCapabilityUnsupportedError` (`Driver`, `Dimension`, `Value`)	A valid, explicitly selected sandbox, web-search, or browser value is unsupported.
`ErrHumanDecisionModeUnsupported`	`driver.ErrHumanDecisionModeUnsupported`	`*adaptor.HumanDecisionModeUnsupportedError` (`Driver`, `Kind`, `Mode`)	An explicit approval mode is absent from `Descriptor.RunPolicyCaps`.

Typed errors preserve lower-level causes where their contracts say so. InvalidDriverConfigError and InvalidOutputSchemaError join their sentinel with Cause. SkillMaterializationError matches its SDK sentinel through an Is method while unwrapping the materializer cause.

var invalid *adaptor.InvalidPolicyError
if errors.As(err, &invalid) {
	log.Printf("driver=%s field=%s value=%s", invalid.Driver, invalid.Field, invalid.Value)
}

if errors.Is(err, adaptor.ErrInvalidPolicy) {
	// Stable category without typed detail.
}

Host-defined Tool errors

Package tool owns three stable categories. Invalid definitions are retained by tool.Define and surface before Driver.Run; input and output failures are validated at the host-handler boundary.

Sentinel	Meaning
`tool.ErrInvalidDefinition`	The name, description, handler, annotations, Go types, or schemas cannot form a valid Tool.
`tool.ErrInvalidInput`	Provider arguments fail JSON/schema validation or cannot decode into the declared Go input type.
`tool.ErrInvalidOutput`	A handler result cannot encode as JSON or fails its output schema.

tool.Reject(code, message) is deliberately a constructor rather than an additional public error type. It marks an expected, model-visible Tool failure; all other handler errors and panics are sanitized by the internal runtime. tool.AsRejection(err) recognizes only errors minted by tool.Reject, even through wrapping; an application-defined error cannot forge safe-delivery status by implementing a similarly named method.

Root Thread errors

The root Thread API translates store/coordinator failures into application sentinels. Root consumers should match these names rather than depending on a particular store implementation.

Sentinel	Meaning	Typical host action
`ErrThreadStoreRequired`	A stateful Thread operation was requested without `WithThreadStore`.	Fix Agent construction.
`ErrThreadNotFound`	A resume-only key or fork parent has no active record.	Return not-found or offer a new Thread.
`ErrThreadBusy`	Another owner holds the required lease.	Retry with bounded backoff.
`ErrThreadIncompatible`	Driver/config/identity/resolved-environment fingerprint or codec compatibility failed.	Keep the old record; explicitly create a new Thread if desired.
`ErrThreadLeaseLost`	The run lost lease ownership, so its state was not persisted.	Treat the outcome as non-authoritative and investigate the store.
`ErrThreadCheckpointMissing`	A nominally successful Thread run did not prove a healthy resumable checkpoint.	Preserve the previous healthy record and inspect the Driver.
`ErrThreadAlreadyExists`	A fork target key already has an active conversation.	Choose another target key; parent and target remain unchanged.
`ErrResumeRejected`	The Driver rejected a resume and the selected mode did not allow a fresh retry.	Inspect compatibility/auth state or explicitly create a new Thread.

The root contract promises errors.Is for these rows, not store-specific typed details. A driver.SessionConfigFingerprintError can remain discoverable with errors.As inside an ErrThreadIncompatible chain when strict config canonicalization caused the incompatibility.

Approval responder errors

These are method errors from ApprovalRequest.Approve, Deny, and Answer, not run verdicts.

Sentinel	Meaning
`ErrApprovalResolved`	A response already won the exactly-once race.
`ErrApprovalExpired`	The deadline or owning invocation ended before this response. It also matches `ErrApprovalResolved`.
`ErrApprovalKindMismatch`	The response method does not fit the request kind.
`ErrApprovalUnavailable`	The request is nil, zero-valued, or has no run-owned responder.

if err := request.Approve(ctx); err != nil {
	switch {
	case errors.Is(err, adaptor.ErrApprovalExpired):
		// The UI response arrived too late.
	case errors.Is(err, adaptor.ErrApprovalResolved):
		// A duplicate response lost the race.
	}
}

`threadstore` errors

Store implementors and direct store consumers use the leaf identities. The root Thread API translates them to the root Thread categories above.

Sentinel	Typed error	Produced by
`threadstore.ErrBusy`	`*threadstore.BusyError{Target}`	`AcquireLease` while another owner has a live lease.
`threadstore.ErrLeaseLost`	`*threadstore.LeaseLostError{Target}`	`RenewLease` or `Finalize` after owner/token/expiry validation fails.
`threadstore.ErrAlreadyExists`	`*threadstore.AlreadyExistsError{Key}`	Conditional `Finalize` when a key was required to be absent.

All three typed errors unwrap to their sentinel. ReleaseLease is idempotent and does not turn a stale release into ErrLeaseLost.

Driver extension errors

Extension authors should return the canonical driver identities listed in the pre-invocation table. Their typed forms are:

*driver.InvalidDriverConfigError
*driver.InvalidPolicyError
*driver.PolicyCapabilityUnsupportedError
*driver.HumanDecisionModeUnsupportedError
*driver.InvalidOutputSchemaError
*driver.StructuredOutputUnsupportedError

*driver.SessionConfigFingerprintError has no sentinel. Match it with errors.As; its Path, Type, Kind, and Why fields describe only the unsupported Go shape and intentionally do not expose configuration values or map keys.

A2A client errors

Package clients/a2a owns transport/client categories:

Sentinel	Meaning
`a2a.ErrInvalidAgentCard`	The card or selected interface is incomplete or invalid.
`a2a.ErrProtocol`	A request, response, part, or event violates the supported protocol shape.
`a2a.ErrUnauthorized`	The remote endpoint rejected authentication/authorization.
`a2a.ErrNotFound`	The remote task does not exist.
`a2a.ErrUnsupported`	The requested operation or content type is unsupported.
`a2a.ErrUntrustedOrigin`	Credentials would cross an origin not explicitly trusted by client options.

*a2a.ProtocolError exposes Op, Reason, Cause, and sanitized Raw, and unwraps its cause (or ErrProtocol when no cause is set). *a2a.StreamRecoveryError exposes TaskID and unwraps the disconnection or recovery cause; it has no dedicated sentinel.

Hosttool errors

hosttools/sessionrecorder exports:

Sentinel	Meaning
`sessionrecorder.ErrInvalidSessionKey`	A recorder/backend key validator or mandatory path-containment check rejected the key.
`sessionrecorder.ErrJSONLEventBackendClosed`	An operation was attempted after the durable event backend closed.
`sessionrecorder.ErrJSONLEventLogCorrupt`	A malformed, truncated, or inconsistent JSONL audit log could not be replayed faithfully.

hosttools/a2adelegation.DelegationError is a typed remote/business failure with Code, Message, Retryable, RemoteStatus, and Metadata. It implements error but has no sentinel and no unwrap contract.

The profile, memory, and bridge packages currently define no additional SDK-owned stable error sentinels. They return documented standard errors, wrapped root/leaf errors, or external protocol-library errors as appropriate.

Matching rules

Match categories with errors.Is, never string comparison.
Use errors.As only for a documented typed error and keep the pointer target form (var typed *T; errors.As(err, &typed)).
Do not collapse unrelated categories into a global IsConflict or IsExpired helper. Hosts can define domain-specific groupings without freezing them into the SDK.
Preserve the full chain with %w when adding host context.
Treat recommended retries and user-facing status codes as host policy; the SDK defines error identity and semantics, not an HTTP response matrix.

See Run policy, Structured output, and AGENTS.md for the associated behavioral contracts.