Error Types

Reference for ConvexCallError, safe result envelopes, normalization, and serialized errors.

import {
  ConvexCallError,
  isSerializedConvexCallError,
  normalizeConvexError,
  type CallResult,
  type ConvexCallErrorKind,
  type SerializedConvexCallError,
} from 'better-convex-nuxt/errors'

`ConvexCallErrorKind`

type ConvexCallErrorKind = 'authentication' | 'transport' | 'server' | 'unknown'

`ConvexCallError`

Field	Type
`name`	`'ConvexCallError'`
`kind`	`ConvexCallErrorKind`
`message`	`string`
`code`	`string \| undefined`
`status`	`number \| undefined`
`data`	`unknown`
`cause`	`unknown`, runtime-only and non-serialized

toJSON() returns only the public shape without cause.

`CallResult`

type CallResult<T, E = ConvexCallError> = { ok: true; data: T } | { ok: false; error: E }

Mutation/action .safe() and upload queue safe methods use this stable envelope.

`normalizeConvexError`

normalizeConvexError(error: unknown): ConvexCallError

It passes an existing ConvexCallError through, recognizes structured Convex application errors as server, and returns unknown when no stable classification exists. It does not classify from message substrings.

Serialized guard

isSerializedConvexCallError(value): value is SerializedConvexCallError

Use the guard at custom serialization boundaries. Nuxt payload revival is installed by the module automatically.

Report an issue