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.

Throwing and safe calls

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)
}

Use .safe() when the result belongs in normal control flow:

const result = await save.safe({ projectId, name })

if (!result.ok) {
  formError.value = result.error
}

Both styles use the same error contract.

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 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.

Serialized errors

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

The runtime-only cause is deliberately excluded from JSON, structured clone, SSR HTML, and normal inspection. Credentials and raw upstream responses must never be copied into public fields.

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.

Report an issue