Skip to main content

Error messages

Turn a failed Convex call into a message for the user, with your own wording per error code.

Result

Every failed write shows one short message in your application's wording. Known errors get a specific text. Everything else gets one generic text, so no internal detail reaches the user.

Throw errors with a code

In a Convex function, throw a ConvexError with a code and a message:

convex/projects.ts
import { ConvexError, v } from 'convex/values'
import { mutation } from './_generated/server'
import { auth } from './auth'

export const archive = mutation({
  args: { projectId: v.id('projects') },
  handler: async (ctx, { projectId }) => {
    const user = await auth.requireUser(ctx)
    const project = await ctx.db.get(projectId)
    // The same error for a missing project and for a project of another user.
    if (!project || project.ownerId !== user.id)
      throw new ConvexError({
        code: 'PROJECT_NOT_FOUND',
        message: 'Project not found',
      })
    if (project.archived) {
      throw new ConvexError({
        code: 'PROJECT_ARCHIVED',
        message: 'This project is already archived',
      })
    }
    await ctx.db.patch(projectId, { archived: true })
  },
})

The browser receives error.code and error.message from this object. Write message for the user who sees it.

Map codes to your wording

Keep one map in your application. It is the place to translate texts, and it decides which codes the user sees:

app/utils/error-message.ts
import { isConvexCallError, normalizeConvexError } from '@lupinum/better-convex-nuxt/errors'

const messages: Record<string, string> = {
  PROJECT_NOT_FOUND: 'This project no longer exists.',
  PROJECT_ARCHIVED: 'This project is already archived.',
  IDENTITY_CHANGED: 'You signed in as someone else. Try again.',
}

export function errorMessage(cause: unknown, fallback = 'Something went wrong. Try again.') {
  const error = normalizeConvexError(cause)
  if (error.code && error.code in messages) return messages[error.code]
  return fallback
}

export function isCancelled(cause: unknown) {
  return isConvexCallError(normalizeConvexError(cause), 'CANCELLED')
}

normalizeConvexError turns any thrown value into a ConvexCallError. A code that is not in the map gets the fallback text.

Show the message

mutate() rejects with the error. Catch it where the user acted:

app/components/ArchiveButton.vue
<script setup lang="ts">
import { api } from '#convex/api'
import type { Id } from '#convex/dataModel'

const props = defineProps<{ projectId: Id<'projects'> }>()
const toast = useToast() // Nuxt UI; use your own notification component
const { mutate: archive, pending } = useConvexMutation(api.projects.archive)

async function onClick() {
  try {
    await archive({ projectId: props.projectId })
  } catch (cause) {
    if (!isCancelled(cause)) toast.add({ title: errorMessage(cause), color: 'error' })
  }
}
</script>

<template>
  <button :disabled="pending" @click="onClick">Archive</button>
</template>

The composable already tracks pending and error. You do not need your own loading ref or try/finally.

To show the error inline instead of in a toast, read error from the composable:

vue
<p v-if="error" role="alert">{{ errorMessage(error) }}</p>

Rules

  • Never show error.message of a code that is not in your map. Library errors with kind unknown have the generic text Unknown Convex error, which is not written for users.
  • Do not show a message for CANCELLED. It means that your code or a user switch stopped the call.
  • Forms already map errors to fields. See mapError in the composables reference.
  • In Nitro routes, use toConvexH3Error(error) to send the error as an HTTP error (NuxtError) with the right status.