Repository navigation
Error Codes ai
github-actions[bot] edited this page Nov 17, 2026
·
5 revisions
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 }) |
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference