Skip to main content

Operation error codes

Every code that an operation, a tool or an approval returns, what it means, and what to do.

Operations from @lupinum/better-convex-functions and tools from @lupinum/better-convex-agents fail with a code and a message. The type is ErrorCode:

ts
import { fail, type ErrorCode } from '@lupinum/better-convex-functions'

Your own handlers use the same codes: fail('INVALID_INPUT', 'name: use 1 to 100 characters.'). A misspelled code is a type error.

A third argument tells the caller why the call failed and what to do. Write it for the person or agent who reads it:

ts
fail('INVALID_INPUT', 'name: use 1 to 100 characters.', {
  why: 'Project names are shown in lists.',
  fix: 'Shorten the name to 100 characters or fewer.',
})

NOT_FOUND and FAILED take no why or fix. NOT_FOUND must read like a missing row, so it cannot tell that a row exists that the actor may not see. FAILED keeps its detail in the log.

Where the code arrives

CallerWhat it receives
The web clientA ConvexCallError of kind server. error.code is the code. Check it with isConvexCallError(error, 'FORBIDDEN')
An MCP host or in-app agentA tool result { error: { code, message, why?, fix? } }, marked as an error
The approval pageapprove returns { status: 'failed', error: { code, message } } for a failure of the approved work

An error without a code never reaches a caller with its details. The web client gets a generic message, an agent gets FAILED, and the detail goes to the Convex log. See Error types.

An agent sees only the codes below. A ConvexError with any other code, for example from a component or a dependency, reaches an agent as FAILED, so its message cannot leak private text to the model. Use fail with one of these codes for a failure the agent should read.

Codes

CodeMeaningWhat to do
NOT_SIGNED_INThe call has no session, and the action is not publicSend the person to sign-in
ACCOUNT_DISABLEDThe session is valid, but your user function returned null: the account is suspended or has no profile yetTell the person the account cannot use the app. Check the users row
FORBIDDENThe caller exists, but the role, the scopes or the agent rule do not allow this action here, or the IDs come from two tenantsHide the action for this role (can). For an agent: grant the scope, or let a person do it
NOT_FOUNDThe row does not exist, or the caller may not know that it exists (another tenant)Refresh the list. Do not retry with the same ID
INVALID_INPUTAn argument is wrong, or names a row whose state does not allow this. The message names the fieldFix the field. An agent reads the message and corrects its input
AGENT_DISABLEDThe agent's grant ended: the person disconnected the host, signed out, or the grant expiredReconnect the host. An in-app agent: turn it on again
APPROVAL_NOT_FOUNDNo open request with this ID is yours to decide or check, or the work does not run under an approvalCheck the ID. A request of another person or tenant is not visible
APPROVAL_EXPIREDNobody decided the request within 30 minutesThe agent asks again
APPROVAL_DECLINEDA person declined the requestThe agent stops, or asks the person what to change
STALEA row the request was about changed after the agent asked. Nothing was doneThe agent reads the rows again and asks again if the work is still needed
REQUEST_ID_REUSEDThe request_id belongs to a different callSend a new request_id for each new call; reuse it only for a retry of the same call
RATE_LIMITEDA limit was reached: writes per minute, or open requests. The message says which, and when to retryWait as the message says. See Limits
TOO_LARGEToo much at once: more than 1,000 IDs in one call, or more than 500 rows in one requestSplit the work into smaller calls
CONFLICTAnother write to the same rows won, or the row changed since the caller last read itRead again and retry
FAILEDAn unexpected error. The detail is in the Convex log, not in the messageRead the log. Turn a known failure into a coded fail
STALLEDAn in-app agent run stopped answeringStart a new run
MODEL_BUSYThe model service is busy or out of quota (in-app agents)Retry later
MODEL_REFUSEDThe model service refused the request or the key (in-app agents)Check the key and the request
MODEL_FAILEDThe model service did not answer (in-app agents)Retry later
MODEL_TIMEOUTThe model service took too long (in-app agents)Retry later, or ask for less

STALLED and the MODEL_* codes belong to the in-app agent runtime. These packages reserve them; their own functions do not raise them.

Errors while you build

These are not codes. They are errors with a message, raised while Convex loads your modules or while a call runs, so you see them in development.

Message starts withCauseFix
Operation action "…" is not in the policy's actionsAn operation names an action that policy.actions does not listAdd the action to the policy
… is a query, so it cannot wait for approvalThe agent rule of a query's action is 'approve' or a functionSet it to 'allow' or 'deny', or make the guarded part a mutation
A query on … returned a row this call may not readA query is missing the filter that its table's rule checksRead by an index on the tenant or owner field, or on the publicRead condition
… is not an internal operation, so it cannot run as this call's actorAn operation called or scheduled a function built with Convex's buildersBuild it with internalQuery, internalMutation or internalAction from defineFunctions
This call reached a function that is not an internal operationThe same, found after the raw function ran. Nothing of the call is keptThe same
System tables are not available to operationsA handler read ctx.db.systemRead system tables in a job, or keep what you need in your own table
Tool name "…"A tool name has characters that some hosts rejectUse 1 to 64 letters, digits, _ or -
Two operations use the tool name …Two operations share a tool nameRename one
…: the argument name request_id is reservedA mutation tool has an argument called request_idRename the argument
Job …: the argument name … is reservedA job has an argument called actingAs, input, inner or traceRename the argument
…: a paginated tool gets cursor and limit from the libraryA paginated query has its own cursor or limit argumentRename the argument
Not exported from the agents module: …A tool function is not exported from the module that calls defineToolsAdd the names to export const { … } = tools.functions
Set the SITE_URL environment variable on the Convex deploymentAn agent asked for approval, and SITE_URL is not setSet SITE_URL to the public origin of your application