Skip to content

Error Codes ai

github-actions[bot] edited this page Nov 17, 2026 · 5 revisions

Error codes: @ultimat3/ai

Part of Error codes: every code @ultimat3/ai registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_AGENT_CONTEXT_EXHAUSTED an agent's next request would not fit its model's context window an agent()'s next request was estimated over the model's contextWindow less maxTokens, and auto-compaction (compact, default 'auto') could not bring it under: there were no turns older than keepTurns to summarise, the summary call failed (no text, cut off, refused, unreachable), or the compacted request still did not fit. Raised before the request is sent, never as a truncated transcript — or, as of 2026-11, after a provider refused the turn as over the window (X_AI_CONTEXT_OVERFLOW) and the one forced compaction failed or was refused too (meta.refused holds the provider's text) compact: { at: 0.6, keepTurns: 2 } — on the agent — compact earlier and keep fewer turns verbatim; or lower maxToolResultChars, or run on a model whose registerModel row has a larger contextWindow
X_AGENT_DEADLINE an agent ran past its declared deadline and was stopped an agent() declared deadlineMs and the run was still going when it elapsed: the model call in flight was aborted, each running tool's ctx.signal fired, and no further turn or tool was started. The run has no answer; tools that already ran keep their effects, and one that ignores its signal still finishes. Terminal: a job does not retry it deadlineMs: 300_000 — on the agent, only once a trace shows the run converging; otherwise lower maxTurns, or shorten the slow tool the agent.turn span events name
X_AGENT_MAX_TURNS an agent hit its turn ceiling without answering an agent() loop with no exit condition — a tool that answers the same thing every turn, or a prompt that never tells the model to finish. Never a partial answer: the loop's whole contract is that it either satisfies output or says it did not, and a half-finished transcript returned as a result is a model's working notes presented as a decision. Raising the ceiling on a non-converging loop spends more money on the same non-answer, which is why the fix names the prompt before the number definePrompt({ id, version, template }) — tell the template when to stop and answer through the respond tool, then bump its version; raise maxTurns only once the run demonstrably converges
X_AGENT_TOOL_LOOP an agent repeated one tool call with one result and was stopped an agent() asked for the same tool calls with the same arguments and read the same results on consecutive turns — or went round a cycle of 2 or 3 such turns — so no later turn can differ. Stopped at maxRepeatedToolCalls (default 3) laps instead of spending every remaining turn re-sending a growing transcript for the same non-answer. Terminal: a job does not retry it maxRepeatedToolCalls: 5 — on the agent, only for a tool that is polled and answers identically while it waits; otherwise tell the template what to do when a tool result does not change, then bump its version
X_AGENT_TOOL_UNDECLARED an agent run offered a tool its declaration does not list an agent()'s offerTools() returned a name that is not one of the declared tools' names (the export name of an action, the name of an inProcessTool()). Refused before anything is loaded, reserved or sent: offerTools() narrows the declared catalogue for one run and can never add to it return only names from the agent's tools from offerTools() — add the tool to tools: on the agent declaration first if the run really needs it
X_AGENT_TOOL_UNEXPOSED an agent lists a tool that is neither in-process nor an MCP-exposed action an agent({ tools }) entry that is an action declaring no mcp block, or mcp: { expose: false }, and is not an inProcessTool(). Refused at declaration rather than filtered at the call, because a silently dropped tool is the worst of both: the declaration reads as if the model can call it, and the model is never offered it inProcessTool({ name, description, input, execute }) for a tool only this agent may call; or add mcp: { expose: true } to the action to offer it to MCP clients too; or drop it from the agent's tools
X_AGENT_TRANSCRIPT_INVALID an agent was asked to continue from a transcript it cannot read agent.continue() was handed a handle that is not the value a .run() or .continue() of the same agent and prompt version returned: another version or agent, over 2,000,000 characters, messages out of order, a block a tool loop never writes, a tool call nothing answers, or an empty user turn. Refused before anything is loaded, reserved or sent agent.run(input, { ctx }) — start a new run and store its transcript; pass back exactly that value
X_AI_BUDGET_EXCEEDED a model call would exceed its budget prompt too large, or cost cap reached budget: { <scope>: <ceiling> } on providerGateway({ budget }) or the llm()/agent() declaration — the fix: line names the key and the value that covers the call — or shorten the prompt
X_AI_CONTENT_UNSUPPORTED an image or document block the role, model or wire format cannot take a media block in a non-user turn, to a model whose row omits the kind from input, or a source the wire format has no shape for registerModel({ ...spec, input: ['image', 'document'] }) — or move the block into a user turn, or send the source the cause names
X_AI_CONTEXT_OVERFLOW a provider refused a request as longer than the model context window a provider answered 400 or 413 with a body saying the prompt outgrew the model's context window (Anthropic 'prompt is too long', OpenAI 'maximum context length', and the other phrases in packages/ai/src/context-overflow.ts). Never retried and never sent to a second provider: the same request overflows every one. agent() compacts once and re-sends before it stops with X_AGENT_CONTEXT_EXHAUSTED; llm() and a direct generate() raise it as itself; terminal for a job compact: { at: 0.6, keepTurns: 2 } — on the agent — or shorten the prompt, or route to a model whose registerModel row has a larger contextWindow
X_AI_EMBEDDER_INVALID an Embedder returned fewer vectors than texts it was given embedOne got an empty batch back from embed([text]) embed: (texts) => Promise.all(texts.map(vectorFor)) — one vector per input text, in the order the texts arrived
X_AI_GATEWAY_MISSING an llm() action ran with no gateway installed no aiGateway in apps/<app>/runtime.ts apps/<app>/runtime.ts: export const runtime = { aiGateway: providerGateway({ providers: [provider] }) } — in a test, installAiGateway(gateway) from @ultimat3/ai/adapter — any provider: the Anthropic format, the OpenAI format (any compatible server), or your own
X_AI_KEY_MISSING the provider API key is not set ANTHROPIC_API_KEY / EMBEDDINGS_API_KEY unset and no apiKey passed export ANTHROPIC_API_KEY=<key>, or pass { apiKey } to the provider
X_AI_MODEL_UNKNOWN a model id the app never registered (the framework registers none since 25.0.0) a model: no registerModel() call describes. This is what replaced the closed ModelId union: the union made a company's own model id inexpressible, so the only way past tsc was to claim a Claude id — and then costOf priced an internal model at Anthropic list rates and the budget ledger reserved against a number belonging to a model nobody ran. A wrong id is still refused; it is refused at the first read of the spec instead of by making a right one impossible. cause lists what is registered registerModel({ id, contextWindow, maxOutput, inputPerMillion, outputPerMillion, cacheMinimumTokens, reasoning }) at boot, before configureAi
X_AI_MODEL_UNRESOLVED a model call named no model neither the declaration, its prompt, nor providerGateway({ defaultModel }) named one — the framework chooses no model for an app llm({ ..., model: modelId }) — or model: modelId in its definePrompt, or providerGateway({ ..., defaultModel: modelId }); register the id with registerModel
X_AI_PROMPT_SECRET a Secret was about to be rendered into a prompt a Secret passed through vars(). Nothing would have leaked — Secret redacts by value, so the template would have received [redacted] and asked the model to reason about it, which is a prompt that reads fine and means something else. The same class of failure as an unfilled {{slot}}, refused for the same reason: loudly, before a token is spent drop the key from vars() and from the template, or revealSecret(value) in vars() if the model genuinely has to read it
X_AI_PROMPT_VERSION prompt version or slots are wrong an edited prompt with no version bump, or a missing variable definePrompt({ id, version, template }) with a new version, then x manifest; an unfilled slot is the { … } vars() returns
X_AI_PROVIDER_UNAVAILABLE the model provider is unreachable a non-2xx, an in-band error event, or a stream cut before message_stop. Never a local refusal, As of 2026-08-23: X_AI_KEY_MISSING and X_AI_REQUEST_INVALID are raised before the socket opens and reach the caller verbatim, keeping their own fix:, instead of being collected into this code by the fallback loop providerGateway({ providers: [provider] }) with a provider whose { models } lists the model; once one is asked and fails, x doctor --json — retry a 429/5xx (the gateway already does); fix the request a 4xx names
X_AI_PROVIDER_UNEXPECTED a provider ended a turn with an unknown reason and an incomplete answer a chat-completions endpoint finished a turn with a finish_reason this build does not know and the answer is not whole (a tool call whose arguments do not parse), or the reason was error. Not truncation and not a transport failure: the endpoint answered and billed, and meta.billed carries the usage and cost; meta.reason is the raw reason x doctor --json, then check what the endpoint means by the reason: a truncation needs a higher maxTokens: on the declaration
X_AI_REQUEST_INVALID the provider would reject this request a reasoning control the chosen model does not have — effort or adaptive thinking on a pre-4.6 model, or thinking: 'disabled' above a model's effort cap set model: on the llm() declaration to one whose MODELS row has the control, or drop effort/thinking from definePrompt — editing the template alone leaves the control in the request
X_AI_SCRIPT_EXHAUSTED a scriptedProvider was called more times than it has turns the code under test asked the model for one more turn than scriptedProvider({ turns }) scripted: a loop that never calls respond, or a script one turn short. Never answered by repeating the last turn, so a runaway loop cannot read as a pass scriptedProvider({ turns: [...turns, { answer: { /* the expected output */ } }] }) # one more turn, or fix the loop that keeps calling the model
X_EVAL_BASELINE_INVALID a recorded baseline cannot be read a hand-edited or half-merged baseline file ULTIMATE_EVAL_RECORD=1 x test eval to re-record it
X_EVAL_BASELINE_MISSING an eval has no recorded baseline to gate against a new eval, or a baseline: that is not import.meta.resolve('./…') ULTIMATE_EVAL_RECORD=1 x test eval, then commit the baseline file
X_EVAL_MISSING a prompt has no eval a definePrompt with no defineEval naming it defineEval({ name, prompt, cases, scorers, tolerance, baseline }) beside the prompt — for a prompt an agent() runs, defineEval({ name, agent, cases, tools, scorers, tolerance, baseline }) — then ULTIMATE_EVAL_RECORD=1 x test eval
X_EVAL_RECORDING the gate ran with baseline recording switched on ULTIMATE_EVAL_RECORD was exported in the shell, or set on the CI job, that ran x verify env -u ULTIMATE_EVAL_RECORD x verify — record with ULTIMATE_EVAL_RECORD=1 x test eval instead
X_EVAL_THRESHOLD an eval scored below its tolerance a prompt edit regressed cases against the recorded baseline x test <eval> for per-case scores; ULTIMATE_EVAL_RECORD=1 x test eval to accept new numbers as a reviewed diff
X_EVAL_TOOL_UNDOUBLED an agent eval called a tool with no double an agent eval's model called a tool the defineEval declares no double for, and an eval never runs a real tool add the tool to tools: on the defineEval, e.g. tools: { lookupOrder: (input) => ({ status: 'shipped' }) }
X_HIVE_EMPTY a hive() split into zero members, so the fan-out ran nothing split() returned an empty list — usually a query behind it that matched no rows. Refused rather than returned, because 0 ok, 0 failed, 0 skipped reads identically for "there was genuinely nothing to do" and "the source query came back empty and nobody noticed", and only the call site can tell them apart. A hive whose empty case is legitimate says so by not being called return at least one member input from the hive's split(), or guard the call site — if (postIds.length > 0) await summariseBacklog({ postIds }, { ctx })
X_LLM_OUTPUT_INVALID structured output failed its schema on the answer and on the repair turn the model would not produce the shape definePrompt({ id, version, template }) — describe the shape in the template and bump its version, or widen output in the llm() declaration
X_LLM_REFUSED the model declined the request the provider's safety classifiers refused; stopDetails.category names why model: '<id>' on the llm() declaration — a more capable model your app registered (the thrown fix: names one) — or edit the template in definePrompt and bump its version
X_LLM_STREAM_INVALID a streamed answer failed its output schema, and a stream cannot repair .stream() on an llm() whose output the tokens did not satisfy. Distinct from X_LLM_OUTPUT_INVALID because there is no repair turn to have failed: the consumer has already read the tokens, and replaying a second answer over the top is two answers to one question await action(input, { ctx }) instead of .stream() when the answer must satisfy a structured schema — a stream has already delivered its tokens and cannot take a repair turn
X_LLM_TOOL_ARGUMENTS_INVALID a finished turn called a tool with arguments that are not JSON the model completed its turn (the stop reason is not a truncation) and the argument string of a tool call does not parse — or streamed fragments carried no index and no id, so two calls could not be told apart. The provider answered and billed: meta.billed carries the usage and cost, the gateway records them on the ledger and does not retry. A turn cut off mid-arguments is X_LLM_TRUNCATED instead. terminal for a job: it dead-letters on the first attempt maxTokens: 8192 on the llm() / agent() declaration if the arguments were long, and shorten or split the string fields of the tool's input schema; to run the same request once more, catch the code in the job and re-enqueue it deliberately — a retry policy does not apply
X_LLM_TRUNCATED the answer hit its maxTokens ceiling before it was complete the ceiling is below what the output schema asks for; the stop reason is read before the schema, so a cut-off answer is never accepted { maxTokens: <double> } on the llm() or agent() declaration — the fix: line names the value — or drop fields from its output schema
X_VECTOR_DIM_MISMATCH embedding dimensions differ from the store the embedder model changed, or the provider returned a width the embedder was not declared with. The fix used to name x ai reindex, which never shipped and is not planned (X_CLI_UNKNOWN_COMMAND, Known gaps) — a fix line naming it sends an operator to a wall { dimension: <width> } — the embedder that created the store, or re-embed every record at the new width and upsert it; for a declared/returned mismatch, the width the provider returned
X_VECTOR_SCOPE_WIDENED a derived vector scope tried to leave its tenant a handler re-scoped the store it was handed vectorStore.scoped({ tenant }), derived from the unscoped store
X_VECTOR_UNSCOPED a vector store was read or written with no tenant bound inside an org request a store is unscoped until .scoped({ tenant }) binds one, and a read or write without it inside any request would reach every tenant's rows, for an org-less or anonymous actor too (a delete or prune removes every org's rows sharing the id); a single-tenant app or a backfill opens the store with scope: UNSCOPED vectorStore.scoped({ tenant: ctx.actor.orgId })

Clone this wiki locally