Errors and Failures

Understand the shared Convex error categories and who owns recovery.

Better Convex Nuxt exposes one public call error across client composables and server helpers: ConvexCallError.

Error kinds

Kind	Meaning	Typical owner of recovery
`authentication`	Required identity is missing, token exchange failed with auth status, or identity changed during a call	Auth UI or operation caller
`transport`	Network, timeout, abort, malformed response, or library-owned HTTP boundary failure	Retry/offline UI or operator
`server`	A structured Convex application/function error	Application workflow
`unknown`	No stable mechanical classification is available	Fallback handling and diagnostics

There is no generic validation kind. The module does not infer categories from message text.

One rejected-Promise contract

Mutation and action wrappers are callable. Normal calls reject with ConvexCallError:

const save = useConvexMutation(api.projects.update)

try {
  await save({ projectId, name })
} catch (error) {
  const callError = normalizeConvexError(error)
  reportFailure(callError.kind)
}

Forms use the same try/catch path. There is no second safe-result protocol; callers decide how to project a caught error into local UI state.

Domain meaning belongs to the application

A Convex function can throw structured ConvexError data such as:

throw new ConvexError({
  code: 'PROJECT_ARCHIVED',
  message: 'Archived projects cannot be edited',
})

The module classifies this as server, gives it the fixed display message Convex application error, and preserves structured data. Your application decides that PROJECT_ARCHIVED disables editing or redirects elsewhere.

Do not parse the display message to discover business meaning.

Only a ConvexCallError explicitly constructed by the application or a library-owned boundary retains its reviewed message. Raw Convex wire errors use the fixed application-error message above. Unclassified strings, objects, and errors use Unknown Convex error. This rule is identical in browser, SSR, and server calls.

Serialized errors

SSR errors cross the Nuxt payload as a public serialized shape. The client revives that shape as ConvexCallError.

ConvexCallError does not retain a raw upstream cause. JSON, structured clone, SSR HTML, normal inspection, and direct property access therefore cannot recover an upstream response body, credential, stack, or request object from the public error. Use reviewed public fields for product behavior and application-owned static operation/correlation metadata for server diagnostics.

Retry is contextual

Retry a transient transport failure when the operation is safe to repeat.
Do not retry authentication failures until auth state changes.
Let the product workflow decide whether a server error is retryable.
Do not retry unknown mutation failures blindly; the write may have reached the server.

See error handling for UI patterns and credentials and security for server-boundary controls.