Failure codes¶

A Failure carries a stable code, a caller-safe message and a private cause. Only the code and message reach the wire; in compact mode as {"failure":{"code":"...","message":"...","retryable":...}} with isError true, in direct mode inside the same envelope, and for resource reads as JSON-RPC error data. Retryable is true only for busy and read_failed, and nothing in the module retries on a caller's behalf.

Operation failures¶

Code	Raised when
`unavailable`	The operation is unknown to this caller, denied by policy, or (Cobra) the binding is shutting down or the child could not be started. Unknown and denied are indistinguishable.
`invalid_arguments`	Arguments fail the input schema, exceed the argument budget, fall outside the numeric profile, or (Cobra) name a flag the command does not accept or a value the CLI cannot express.
`busy`	A confirmation transition is already in progress for this chain, the continuation ledger is at capacity, or (Cobra) every execution slot is taken. Retryable.
`timeout`	The caller's deadline passed, or (Cobra) the execution timeout elapsed.
`cancelled`	The caller's context was cancelled, or the host shut the binding down mid-run.
`confirmation_required`	The handler asked for form or URL input and the caller declared no support for that mode.
`interaction_declined`	The user declined a prompt.
`interaction_cancelled`	The user cancelled a prompt.
`interaction_limit`	An eleventh prompt in one chain (the default is ten).
`continuation_invalid`	A token that is malformed, forged, for another operation or caller, or whose answer conflicts with the recorded one.
`continuation_stale`	A token from a previous server lifetime or an expired prompt.
`invalid_result`	A handler returned no outcome, an unconstructed result, structured output that fails the output schema, or (Apps) an unapproved view; also a definition or schema the registry could not compile.
`result_too_large`	A result exceeds the core result budget or the adapter's 16 MiB wire ceiling.
`command_failed`	(Cobra) The child exited non-zero. The result still carries stdout, stderr and the exit code as diagnostics.
`cleanup_failed`	(Cobra) The child or a managed descendant could not be confirmed stopped within the cleanup budget; the execution slot stays taken and `Binding.Status()` reports it. (Server) `Shutdown` ran out of budget.
`read_failed`	A resource read failed. Retryable.
`internal`	Anything the module could not classify, including a `NewFailure` call with an invalid code or message.

Resource issue codes¶

A partial bundle reports per-item issues under go.phpboyscout.uk/mcp.resourceRead with these codes only: unavailable, read_failed (retryable), timeout, invalid_content, budget_exceeded. Messages are fixed templates and never carry a private cause.

Protocol errors¶

Malformed envelopes, unknown outer tools in compact mode, oversized frames and invalid continuation pairs are JSON-RPC errors from the adapter, not operation failures. A failed resource read is a JSON-RPC error carrying safe code, message and retryable data.

Cobra exit codes¶

The compatibility result's exitCode is the child's exit status, 0 on success. A child that could not be waited on (killed by the cleanup, or a non-exit error) reports -1.