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` and offer `refresh()` where safe
Mutation/action	Call directly, catch, and map structured domain errors
Auth operation	Inspect Better Auth operation result plus reactive auth error
Upload	Render upload `error`; retry with a new explicit user action
Server route	Catch and map to a safe HTTP contract

Query retry

vue

<section v-if="error">
  <p>Projects are unavailable.</p>
  <button @click="refresh">Try again</button>
</section>

Do not retry a required query while auth is anonymous. Let auth state change first.

Structured server errors

try {
  await archiveProject({ projectId })
} catch (rawError) {
  const error = normalizeConvexError(rawError)
  const data = error.data as { code?: string }
  if (data.code === 'PROJECT_ALREADY_ARCHIVED') {
    await navigateTo('/archive')
  }
}

Use structured data.code, not message substrings.

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.

Log the category, operation name, 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.