Error Handling

AvatarError type

All SDK errors follow this shape — surfaced via the error state from useAvatar and the error event from useAvatarEvent.

type AvatarError = {
  // --- Branch on these ---
  code: AvatarErrorCode;      // What went wrong, in terms of what you can do
  fatal: boolean;             // Is the session over?
  retryable: boolean;         // Would calling start() again help?

  // --- Log these; don't render them ---
  message: string;            // Written for you, not your users
  source: AvatarErrorSource;  // "network" | "server" | "sdk"
  cause?: unknown;            // The underlying JS error, if any
};

fatal is about the call, not the avatar

These are two separate questions, and an error only answers the first one:

• fatal — is the call over?
• isReady (from useAvatar) — is there still an avatar on screen?

The same code lands differently depending on when it fires. A connection failure during a cold start leaves an empty frame; the identical failure ten seconds into a call leaves the avatar exactly where it was. So code can't tell you what to render, and neither can fatal — isReady can:

| | isReady | what to do | |---|---|---| | fatal | true | Avatar's still there. Toast the reason; your start control is the retry. | | fatal | false | Nothing to show — this is what errorFallback is for. | | not fatal | — | The call is still live. Toast at most. |

The good news is you rarely write that table yourself: <Avatar> reads it for you (see below).

The two fields that matter

fatal — is the session over?

• true — the call is over, and the SDK has already cleaned it up. The avatar stays on screen; start() opens a new call. Tell them why, and let your existing start control be the retry.
• false — the session is still live. One specific thing failed (a single turn, one dropped speakText) and the call continues underneath. Show a transient hint, or ignore it.

retryable — would start() plausibly succeed? Only meaningful when fatal. Every fatal error is retryable except MIC_PERMISSION_DENIED, where the user must change a browser setting first. Use it to decide whether to render a Retry button, so you never show one that can't work.

Error codes

Codes are grouped by who fixes it. There are fewer of them than you might expect, because a code only exists where the fix differs. If you need to know exactly which call failed, that detail is in message and cause.

Your integration

You fix these in your own code. All are non-fatal except the token failure — they report a dropped call, not a broken session.

Your user

The service

Retry, or report to us.

Lifecycle

The minimum that works

If you do nothing at all, <Avatar> renders a built-in card whenever a fatal error leaves nothing painted, so you never ship a blank frame. Override the copy with errorFallback:

<Avatar loader={<Spinner />} errorFallback={<CouldNotConnect />} />

Handling via state

You don't need to know the code list to do this correctly:

A fatal error ends the session, not the avatar. stop() deliberately keeps the avatar painted so restarting is cheap, and isIdle flips back to true — so your existing start control reappears and is the retry. There is usually nothing to rebuild:

function CallStage() {
  // No error branch at all. An idle timeout or a dropped connection ends the
  // session and leaves the avatar on screen; the controls' button flips back to
  // "Start" on its own. Replacing this with a dead-end screen would throw away
  // a working avatar AND the control that fixes it.
  return <Avatar errorFallback={<CouldNotLoad />} />;
}

errorFallback covers the case with nothing to show. <Avatar> decides that by looking at whether an avatar is actually on screen — not at the code — so it stays right regardless of which error fired or when. AVATAR_LOAD_FAILED is the usual one, but a token failure or a dropped connection before the first render lands there too.

Then tell them why the call ended, in a toast, with copy written for them:

const COPY: Partial<Record<AvatarErrorCode, string>> = {
  MIC_PERMISSION_DENIED: "Allow microphone access in your browser settings.",
  SESSION_IDLE_TIMEOUT: "The call ended after a stretch of silence.",
  CONNECTION_FAILED: "We couldn't reach the service. Check your connection.",
};

function ErrorToast() {
  const { error } = useAvatar();
  useEffect(() => {
    if (!error) return;
    toast(COPY[error.code] ?? "Something went wrong on our side.");
  }, [error]);
  return null;
}

Non-fatal errors belong in a toast, not a screen — the call is still running underneath, so replacing the avatar would be a downgrade:

function TurnHiccupToast() {
  const { error } = useAvatar();
  if (!error || error.fatal) return null;
  // e.g. BRAIN_ERROR — the avatar just missed a turn. Still connected.
  return <Toast>Sorry, I missed that — try again?</Toast>;
}

Handling via events

Use useAvatarEvent("error", ...) for analytics and logging — this is where the diagnostic fields earn their keep.

function ErrorHandler() {
  useAvatarEvent("error", (error) => {
    // Send the full detail somewhere you can read it later. `message` and
    // `cause` belong HERE, not on screen.
    analytics.track("avatar_error", {
      code: error.code,
      source: error.source,
      fatal: error.fatal,
      message: error.message,
    });
  });

  return null;
}

While you're integrating

INVALID_MODE, INVALID_INPUT, and NOT_CONNECTED mean your code has a bug, not that anything failed at runtime. They're non-fatal and the session is untouched. Wire this up once and they'll tell you in development:

useAvatarEvent("error", (err) => {
  if (err.source === "sdk" && !err.fatal) {
    console.warn(`[avatar] ${err.code}: ${err.message}`);
  }
});

Fatal vs non-fatal