{"record":{"id":"a7240f223b9334d7","repo":"mastra-ai/mastra","slug":"mastra-livekit-set-livekit-api-key-and-livekit-a","errorCode":null,"errorMessage":"@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.","messagePattern":"@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integrations/livekit/src/dispatch.ts","lineNumber":36,"sourceCode":"}\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":18,"sourceCodeEnd":45,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/integrations/livekit/src/dispatch.ts#L18-L45","documentation":"dispatchVoiceSession creates a LiveKit agent dispatch via AgentDispatchClient, which requires credentials. The function checks options.apiKey/options.apiSecret first, then falls back to LIVEKIT_API_KEY/LIVEKIT_API_SECRET env vars; it throws when both are missing so it never calls LiveKit with anonymous credentials.","triggerScenarios":"Calling dispatchVoiceSession without passing apiKey/apiSecret while neither LIVEKIT_API_KEY nor LIVEKIT_API_SECRET is set in the environment.","commonSituations":"Deploying to an environment where .env is not loaded (serverless, CI, containers); setting only LIVEKIT_URL; forgetting to propagate secrets to a worker process that dispatches sessions.","solutions":["Set both LIVEKIT_API_KEY and LIVEKIT_API_SECRET in the environment running dispatchVoiceSession (from a LiveKit cloud API key or self-hosted key/secret pair).","Alternatively pass apiKey and apiSecret explicitly in the options object to dispatchVoiceSession.","Verify the secrets are actually loaded at runtime (e.g. dotenv config or platform secret injection) before dispatching."],"exampleFix":"// before\nawait dispatchVoiceSession({ roomName: 'call-1', serverUrl });\n// after\nawait dispatchVoiceSession({\n  roomName: 'call-1',\n  serverUrl,\n  apiKey: process.env.LIVEKIT_API_KEY,\n  apiSecret: process.env.LIVEKIT_API_SECRET,\n});","handlingStrategy":"validation","validationCode":"function assertLiveKitCredentials(opts = {}) {\n  const key = opts.apiKey ?? process.env.LIVEKIT_API_KEY;\n  const secret = opts.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n  if (!key || !secret) throw new Error('LiveKit dispatch needs apiKey/apiSecret or LIVEKIT_API_KEY/LIVEKIT_API_SECRET env vars');\n  return { apiKey: key, apiSecret: secret };\n}\nassertLiveKitCredentials(); // run before dispatchVoiceSession","typeGuard":null,"tryCatchPattern":"try {\n  await dispatchVoiceSession(opts);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('LIVEKIT_API_KEY')) {\n    // fail fast: missing credentials, do not retry\n  }\n  throw e;\n}","preventionTips":["Validate required LiveKit env vars at process startup, not at dispatch time.","Include LIVEKIT_API_KEY/SECRET in deploy checklist and secret manager config.","Load .env explicitly in non-hosted environments (dotenv)."],"tags":["configuration","credentials","environment-variables","livekit"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}