{"record":{"id":"7e3679c0b0f71664","repo":"mastra-ai/mastra","slug":"mastra-livekit-set-livekit-url-or-pass-serverurl","errorCode":null,"errorMessage":"@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.","messagePattern":"@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integrations/livekit/src/dispatch.ts","lineNumber":33,"sourceCode":"  apiKey?: string;\n  /** Defaults to `LIVEKIT_API_SECRET`. */\n  apiSecret?: string;\n}\n\nfunction toHttpUrl(url: string): string {\n  return url.replace(/^ws/, 'http');\n}\n\n/**\n * Programmatically dispatches a Mastra voice agent into a LiveKit room — for\n * server-initiated sessions such as outbound calls or joining an existing room.\n */\nexport async function dispatchVoiceSession(options: DispatchVoiceSessionOptions) {\n  const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;\n  const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;\n  const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n  if (!serverUrl) {\n    throw new Error('@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.');\n  }\n  if (!apiKey || !apiSecret) {\n    throw new Error(\n      '@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.',\n    );\n  }\n  const client = new AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret);\n  return client.createDispatch(options.roomName, options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME, {\n    metadata: serializeSessionMetadata(options.metadata ?? {}),\n  });\n}\n","sourceCodeStart":15,"sourceCodeEnd":45,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/integrations/livekit/src/dispatch.ts#L15-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":".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.","solutions":["Set the LIVEKIT_URL environment variable (e.g. wss://your-project.livekit.cloud).","Or pass it explicitly: dispatchVoiceSession({ serverUrl: 'wss://...', apiKey, apiSecret }).","Ensure dotenv/.env is loaded before dispatchVoiceSession executes.","Verify the exact variable name LIVEKIT_URL in your deployment's secret configuration."],"exampleFix":"// before\nawait dispatchVoiceSession({ apiKey, apiSecret }); // no LIVEKIT_URL in env\n// after\nawait dispatchVoiceSession({ serverUrl: process.env.LIVEKIT_URL, apiKey, apiSecret }); // with LIVEKIT_URL set","handlingStrategy":"validation","validationCode":"function requireLiveKitEnv(): { serverUrl: string; apiKey: string; apiSecret: string } {\n  const serverUrl = process.env.LIVEKIT_URL;\n  const apiKey = process.env.LIVEKIT_API_KEY;\n  const apiSecret = process.env.LIVEKIT_API_SECRET;\n  if (!serverUrl || !apiKey || !apiSecret) {\n    throw new Error('Set LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET before dispatching voice sessions');\n  }\n  return { serverUrl, apiKey, apiSecret };\n}","typeGuard":null,"tryCatchPattern":"try {\n  await dispatchVoiceSession(options);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('set LIVEKIT_URL')) {\n    throw new Error('Startup config error: LIVEKIT_URL is not configured');\n  }\n  throw err;\n}","preventionTips":["Set LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET together in every environment.","Load dotenv at process startup before dispatching sessions.","Use the exact variable name LIVEKIT_URL (not LIVEKIT_SERVER_URL or LIVEKIT_HOST).","Add a startup env-presence check that fails fast in CI and production."],"tags":["configuration","env-var","livekit","missing-config"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}