Error handling
Handle query, mutation, action, auth, upload, and server failures with one public error model.
Handle errors at the boundary that can make the next decision.
Choose the control flow
| Operation | Normal pattern |
|---|---|
| Query | Render reactive error; Convex re-runs the query when its cause changes |
| Mutation/action | Call mutate or run, catch, and map structured domain errors |
| Form | Render fieldErrors and formError from the submit result |
| Pagination | Show a first-page error by status; retry a later page with loadMore() |
| Auth operation | Inspect Better Auth operation result plus reactive auth error |
| Upload | Render upload error; retry with a new explicit user action |
| Server route | Rethrow with toConvexH3Error, or map to your own HTTP contract |
Query errors
<section v-if="error">
<p>Projects are unavailable.</p>
</section>A query error stays until its cause changes. Convex runs the query again by itself when the data it read changes or new code is deployed, and the error clears. A failed later page is retried with loadMore().
A system failure, such as Function execution timed out, does not come from the data the query read. It can stay until that data changes or the browser reconnects to Convex, which sends every query again. A query has no retry call: the Convex client keeps one subscription for each query and arguments, shared by every component that uses them, so subscribing again from one component gets the same stored failure. While error is set, data keeps the last result, so show it with a notice. When there is no data, offer a page reload, for example with reloadNuxtApp(). A paginated list can try again with restart(), which subscribes its pages under a new pagination id.
Structured server errors
import { isConvexCallError } from '@lupinum/better-convex-nuxt/errors'
const { mutate: archiveProject } = useConvexMutation(api.projects.archive)
async function archive() {
try {
await archiveProject({ projectId })
} catch (error) {
if (isConvexCallError(error, 'PROJECT_ALREADY_ARCHIVED')) {
await navigateTo('/archive')
return
}
toast.error(isConvexCallError(error) ? error.message : 'The project could not be archived.')
}
}Use code, not message substrings, for decisions. A server error's code is the data.code of the ConvexError, and its message is the text the Convex function wrote in data.message. Show that message to the user only when the backend writes user-facing text.
Show why and how to fix it
A Convex function can tell the user why it refused and what they can do. With @lupinum/better-convex-functions, pass why and fix to fail:
fail('INVALID_INPUT', 'The invoice could not be sent.', {
why: 'The client has no email address.',
fix: 'Add an email address in the client settings.',
})Without the functions package, put them in the error data: throw new ConvexError({ code, message, why, fix }).
The ConvexCallError then has why and fix:
<section v-if="error" role="alert">
<p>{{ error.message }}</p>
<p v-if="error.why">{{ error.why }}</p>
<p v-if="error.fix">{{ error.fix }}</p>
</section>Write why and fix for the user. Do not build them from internal state, IDs, or the error text of another service. NOT_FOUND and FAILED take no help, and fail rejects it at compile time: NOT_FOUND must read like a missing row, and FAILED keeps its detail in the log. Agents that call the function through the MCP door receive the same why and fix. They get help only with the library's codes: for a code of your own, the MCP door answers FAILED without it. When work that a person approved fails, only its code and message are kept: the person who approved it and the agent that checks its request see no why or fix.
why and fix are server text in one language. When your app shows its own text for each code, for example in another language, keep that text for people. Then why and fix are for agents, and for a code that has no text of its own.
Quote the request ID
When a Convex function fails, error.requestId holds the Convex request ID of the call. The Convex logs and log streams record the same ID. Show it with an unexpected failure, so that the user can quote it:
<p v-if="error?.requestId">Reference: {{ error.requestId }}</p>To find the call, search for the ID in the logs of your Convex dashboard or in your log stream. On a local backend, npx convex logs --jsonl shows the requestId of each call; the log lines that convex dev prints do not. An unexpected failure (kind unknown) keeps its request ID, but not its text.
Better Convex reads the ID from the error text of Convex, which is not a stable Convex contract. When Convex changes that text, requestId is undefined.
Library error codes
The codes that Better Convex raises itself include IDENTITY_CHANGED, CANCELLED, FILE_TOO_LARGE, FILE_TYPE_NOT_ALLOWED, UPLOAD_IN_PROGRESS, SUBMIT_IN_PROGRESS, UNAUTHENTICATED, CLIENT_UNAVAILABLE, NETWORK_ERROR, and TIMEOUT. The type ConvexCallErrorCode lists every code. Ignore CANCELLED when your own cancel() or reset() caused it. Do not retry IDENTITY_CHANGED automatically. See error types.
Errors from Nitro routes
A route that rethrows with toConvexH3Error returns the serialized error as an HTTP error (NuxtError); on the server, check it with isNuxtError(error) from nuxt/server and read error.status. Revive it in the browser:
import { normalizeConvexError } from '@lupinum/better-convex-nuxt/errors'
try {
await $fetch('/api/reports', { method: 'POST', body })
} catch (raw) {
const error = normalizeConvexError(raw)
reportError.value = error.message
}normalizeConvexError reads the error from the FetchError of $fetch or useFetch. Any other value becomes an unknown error with a generic message.
Error boundaries
Vue/Nuxt error boundaries are appropriate for render failures or page-level inability to continue. A failed button action usually belongs inline and should not replace the whole page.
Logging
Log the category, functionName, requestId, and safe correlation context. Do not log tokens, cookies, auth headers,
raw upload bytes, or upstream error objects. ConvexCallError does not retain the raw upstream cause.
Retry safety
Queries are safe to repeat. Mutations and actions may have committed before a network or identity-transition failure became visible. Add backend idempotency where retries are possible.