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:
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:
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
| Caller | What it receives |
|---|---|
| The web client | A ConvexCallError of kind server. error.code is the code. Check it with isConvexCallError(error, 'FORBIDDEN') |
| An MCP host or in-app agent | A tool result { error: { code, message, why?, fix? } }, marked as an error |
| The approval page | approve 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
| Code | Meaning | What to do |
|---|---|---|
NOT_SIGNED_IN | The call has no session, and the action is not public | Send the person to sign-in |
ACCOUNT_DISABLED | The session is valid, but your user function returned null: the account is suspended or has no profile yet | Tell the person the account cannot use the app. Check the users row |
FORBIDDEN | The caller exists, but the role, the scopes or the agent rule do not allow this action here, or the IDs come from two tenants | Hide the action for this role (can). For an agent: grant the scope, or let a person do it |
NOT_FOUND | The 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_INPUT | An argument is wrong, or names a row whose state does not allow this. The message names the field | Fix the field. An agent reads the message and corrects its input |
AGENT_DISABLED | The agent's grant ended: the person disconnected the host, signed out, or the grant expired | Reconnect the host. An in-app agent: turn it on again |
APPROVAL_NOT_FOUND | No open request with this ID is yours to decide or check, or the work does not run under an approval | Check the ID. A request of another person or tenant is not visible |
APPROVAL_EXPIRED | Nobody decided the request within 30 minutes | The agent asks again |
APPROVAL_DECLINED | A person declined the request | The agent stops, or asks the person what to change |
STALE | A row the request was about changed after the agent asked. Nothing was done | The agent reads the rows again and asks again if the work is still needed |
REQUEST_ID_REUSED | The request_id belongs to a different call | Send a new request_id for each new call; reuse it only for a retry of the same call |
RATE_LIMITED | A limit was reached: writes per minute, or open requests. The message says which, and when to retry | Wait as the message says. See Limits |
TOO_LARGE | Too much at once: more than 1,000 IDs in one call, or more than 500 rows in one request | Split the work into smaller calls |
CONFLICT | Another write to the same rows won, or the row changed since the caller last read it | Read again and retry |
FAILED | An unexpected error. The detail is in the Convex log, not in the message | Read the log. Turn a known failure into a coded fail |
STALLED | An in-app agent run stopped answering | Start a new run |
MODEL_BUSY | The model service is busy or out of quota (in-app agents) | Retry later |
MODEL_REFUSED | The model service refused the request or the key (in-app agents) | Check the key and the request |
MODEL_FAILED | The model service did not answer (in-app agents) | Retry later |
MODEL_TIMEOUT | The 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 with | Cause | Fix |
|---|---|---|
Operation action "…" is not in the policy's actions | An operation names an action that policy.actions does not list | Add the action to the policy |
… is a query, so it cannot wait for approval | The agent rule of a query's action is 'approve' or a function | Set it to 'allow' or 'deny', or make the guarded part a mutation |
A query on … returned a row this call may not read | A query is missing the filter that its table's rule checks | Read 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 actor | An operation called or scheduled a function built with Convex's builders | Build it with internalQuery, internalMutation or internalAction from defineFunctions |
This call reached a function that is not an internal operation | The same, found after the raw function ran. Nothing of the call is kept | The same |
System tables are not available to operations | A handler read ctx.db.system | Read system tables in a job, or keep what you need in your own table |
Tool name "…" | A tool name has characters that some hosts reject | Use 1 to 64 letters, digits, _ or - |
Two operations use the tool name … | Two operations share a tool name | Rename one |
…: the argument name request_id is reserved | A mutation tool has an argument called request_id | Rename the argument |
Job …: the argument name … is reserved | A job has an argument called actingAs, input, inner or trace | Rename the argument |
…: a paginated tool gets cursor and limit from the library | A paginated query has its own cursor or limit argument | Rename the argument |
Not exported from the agents module: … | A tool function is not exported from the module that calls defineTools | Add the names to export const { … } = tools.functions |
Set the SITE_URL environment variable on the Convex deployment | An agent asked for approval, and SITE_URL is not set | Set SITE_URL to the public origin of your application |