mastra-ai/mastra · error

@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispat

Error message

@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.

What it means

dispatchVoiceSession resolves the LiveKit server URL from options.serverUrl or the LIVEKIT_URL environment variable. When both are absent it throws this fail-fast error, because creating a LiveKit room/token dispatch requires knowing the LiveKit server endpoint. It surfaces before any network call is attempted.

Source

Thrown at integrations/livekit/src/dispatch.ts:33

  apiKey?: string;
  /** Defaults to `LIVEKIT_API_SECRET`. */
  apiSecret?: string;
}

function toHttpUrl(url: string): string {
  return url.replace(/^ws/, 'http');
}

/**
 * Programmatically dispatches a Mastra voice agent into a LiveKit room — for
 * server-initiated sessions such as outbound calls or joining an existing room.
 */
export async function dispatchVoiceSession(options: DispatchVoiceSessionOptions) {
  const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;
  const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;
  const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;
  if (!serverUrl) {
    throw new Error('@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.');
  }
  if (!apiKey || !apiSecret) {
    throw new Error(
      '@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.',
    );
  }
  const client = new AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret);
  return client.createDispatch(options.roomName, options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME, {
    metadata: serializeSessionMetadata(options.metadata ?? {}),
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the LIVEKIT_URL environment variable (e.g. wss://your-project.livekit.cloud).
2. Or pass it explicitly: dispatchVoiceSession({ serverUrl: 'wss://...', apiKey, apiSecret }).
3. Ensure dotenv/.env is loaded before dispatchVoiceSession executes.
4. Verify the exact variable name LIVEKIT_URL in your deployment's secret configuration.

Example fix

// before
await dispatchVoiceSession({ apiKey, apiSecret }); // no LIVEKIT_URL in env
// after
await dispatchVoiceSession({ serverUrl: process.env.LIVEKIT_URL, apiKey, apiSecret }); // with LIVEKIT_URL set

function requireLiveKitEnv(): { serverUrl: string; apiKey: string; apiSecret: string } {
  const serverUrl = process.env.LIVEKIT_URL;
  const apiKey = process.env.LIVEKIT_API_KEY;
  const apiSecret = process.env.LIVEKIT_API_SECRET;
  if (!serverUrl || !apiKey || !apiSecret) {
    throw new Error('Set LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET before dispatching voice sessions');
  }
  return { serverUrl, apiKey, apiSecret };
}

try {
  await dispatchVoiceSession(options);
} catch (err) {
  if (err instanceof Error && err.message.includes('set LIVEKIT_URL')) {
    throw new Error('Startup config error: LIVEKIT_URL is not configured');
  }
  throw err;
}

When it happens

Trigger: Calling dispatchVoiceSession() without options.serverUrl in an environment where process.env.LIVEKIT_URL is unset or empty — local dev without .env, CI without the secret, or serverless deployments missing env configuration.

Common situations: .env file not loaded (dotenv not imported); secret named LIVEKIT_SERVER_URL or LIVEKIT_HOST instead of LIVEKIT_URL; deploying to a new environment without copying LiveKit credentials.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Bright Data API token is required. Pass { apiKey } or set BR
• Auth0 domain and audience are required, please provide them
• Clerk JWKS URI, secret key and publishable key are required,
• Google client ID is required. Provide it in the options or s
• [MastraAuthGoogle] GOOGLE_COOKIE_PASSWORD is required for Go

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/7e3679c0b0f71664. Report an issue: GitHub.