RealtimeVoiceError

Defined in: packages/realtime/src/lib/realtime-voice-error.ts:61

A realtime voice failure with a typed cause.

Thrown from connect() for setup failures and carried on adapter error events for in-session failures. instanceof RealtimeVoiceError is the supported way to distinguish fatal voice errors from benign noise — consumers must never string-match messages.

Severity contract

A RealtimeVoiceError is the fatal signal, and this is its load-bearing invariant: raising one — thrown from connect(), or emitted on an adapter error event — tells RealtimeSession the session can no longer function, so it tears the connection down and enters the error state. A plain Error on an error event is only logged. Adapters must therefore reserve RealtimeVoiceError for genuinely fatal conditions:

Fatal (raise a RealtimeVoiceError) — loss of the underlying connection, which the connection-state paths own and surface: a token mint failure, a transport/mic failure while connecting, or a broken data channel the session drives turns over. Without the connection the session cannot function.
Non-fatal (never raise a RealtimeVoiceError) — a failure that leaves the already-applied UI change intact and the session usable. Failing to deliver the spoken read-back of a tool result is non-fatal: the update_ui already rendered, nothing downstream waits on the confirmation, and a transport that is truly down is either already surfaced as connection loss or an intentional teardown. This covers a worker-reported TTS synthesis failure or a malformed status packet on the read-back channel (only the voiced confirmation was lost), an unrecognized inbound packet, and a read-back attempted after the room is gone. Raising a fatal error here would kill a live session over lost audio. Instead warn once and recover locally (e.g. collapse a transient speaking state so the UI does not hang waiting for audio that will never arrive).

Extends

MaelstromError

Constructors

Constructor

new RealtimeVoiceError(code, message, cause?): RealtimeVoiceError

Defined in: packages/realtime/src/lib/realtime-voice-error.ts:64

Parameters

code

RealtimeVoiceErrorCode

message

string

cause?

unknown

Returns

RealtimeVoiceError

Overrides

MaelstromError.constructor

Properties

cause?

readonly optional cause?: unknown

Defined in: packages/protocol/dist/lib/errors/base.d.ts:12

Inherited from

MaelstromError.cause

code

readonly code: RealtimeVoiceErrorCode

Defined in: packages/realtime/src/lib/realtime-voice-error.ts:62

Overrides

MaelstromError.code

message

message: string

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

MaelstromError.message

name

name: string

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

MaelstromError.name

stack?

optional stack?: string

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

MaelstromError.stack

stackTraceLimit

static stackTraceLimit: number

Defined in: node_modules/.bun/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

MaelstromError.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/.bun/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

MaelstromError.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/.bun/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:56

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

MaelstromError.prepareStackTrace