{"record":{"id":"c89809a16261b64a","repo":"mastra-ai/mastra","slug":"mastra-livekit-no-mastra-agent-specified-set-a","errorCode":null,"errorMessage":"@mastra/livekit: no Mastra agent specified. Set `agent` on createLiveKitWorker or pass `agentId` in the dispatch metadata (e.g. via liveKitConnectionRoute).","messagePattern":"@mastra/livekit: no Mastra agent specified\\. Set `agent` on createLiveKitWorker or pass `agentId` in the dispatch metadata \\(e\\.g\\. via liveKitConnectionRoute\\)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integrations/livekit/src/worker.ts","lineNumber":248,"sourceCode":"      `@mastra/livekit: turnDetection '${kind}' requires '@livekit/agents-plugin-livekit'. ` +\n        \"Install it or use a built-in mode like 'vad' or 'stt'.\",\n      { cause: error },\n    );\n  }\n  return kind === 'english'\n    ? (new plugin.turnDetector.EnglishModel() as TurnDetectionSetting)\n    : (new plugin.turnDetector.MultilingualModel() as TurnDetectionSetting);\n}\n\nasync function resolveMastraAgent(\n  options: CreateLiveKitWorkerOptions,\n  args: ResolveMastraAgentArgs,\n): Promise<MastraAgent> {\n  let ref: string | MastraAgent | undefined =\n    typeof options.agent === 'function' ? await options.agent(args) : options.agent;\n  ref ??= args.metadata.agentId;\n  if (!ref) {\n    throw new Error(\n      '@mastra/livekit: no Mastra agent specified. Set `agent` on createLiveKitWorker or pass ' +\n        '`agentId` in the dispatch metadata (e.g. via liveKitConnectionRoute).',\n    );\n  }\n  if (typeof ref !== 'string') return ref;\n  try {\n    return options.mastra.getAgentById(ref);\n  } catch {\n    return options.mastra.getAgent(ref);\n  }\n}\n\n// Returns the workflow boxed in an object: `Workflow` is thenable (it has a `.then()` builder\n// method), so a bare `Promise<Workflow>` return — or awaiting a `Workflow`-typed value — trips\n// TS's thenable checks and, at runtime, `await workflow` would call the builder's `.then`.\nasync function resolveWorkflow(\n  options: CreateLiveKitWorkerOptions,\n  args: ResolveMastraAgentArgs,","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/integrations/livekit/src/worker.ts#L230-L266","documentation":"resolveMastraAgent determines which Mastra agent the voice worker should talk to: it takes options.agent (value or async function), falls back to the `agentId` in the LiveKit dispatch metadata, and throws if both are absent. Without an agent reference it cannot route the conversation.","triggerScenarios":"createLiveKitWorker called without an `agent` option (or an agent resolver returning undefined), and the room's dispatch metadata (set at dispatch time, e.g. by liveKitConnectionRoute) contains no agentId.","commonSituations":"Worker configured for dynamic per-room agent selection but the dispatch side never set agentId in metadata; agent resolver returning undefined when its lookup fails; migrating from static to dynamic agent config and dropping the default.","solutions":["Set `agent` on createLiveKitWorker (an agent instance, id string, or resolver function).","Ensure dispatch metadata includes agentId when dispatching the session (e.g. via liveKitConnectionRoute or dispatchVoiceSession metadata).","If using an async agent resolver, make sure it resolves to a defined agent/id rather than undefined."],"exampleFix":"// before\ncreateLiveKitWorker({ mastra, workflow: 'voiceFlow' }); // no agent anywhere\n// after\ncreateLiveKitWorker({ mastra, workflow: 'voiceFlow', agent: 'support-agent' });\n// or at dispatch time\nawait dispatchVoiceSession({ roomName, metadata: { agentId: 'support-agent' } });","handlingStrategy":"validation","validationCode":"function assertVoiceAgentConfigured(workerOptions, dispatchMetadata = {}) {\n  const resolved = typeof workerOptions.agent === 'function' ? undefined : workerOptions.agent;\n  if (!resolved && !dispatchMetadata.agentId) {\n    throw new Error('Voice worker needs options.agent or agentId in dispatch metadata');\n  }\n}\nassertVoiceAgentConfigured(opts, roomMetadata);","typeGuard":null,"tryCatchPattern":"try {\n  await startVoiceSession(args);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('no Mastra agent specified')) {\n    console.error('Dispatch metadata keys:', Object.keys(args.metadata)); // debug missing agentId\n  }\n  throw e;\n}","preventionTips":["Always include agentId in dispatch metadata when using per-room dynamic agents.","Set a default `agent` on createLiveKitWorker as a safety net.","Add an integration test that dispatches a session and asserts the worker resolves an agent.","Make agent resolvers throw (not return undefined) when their lookup fails."],"tags":["configuration","routing","agents","livekit"],"backgroundTag":"missing-required-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}