@mastra/livekit: turnDetection '${kind}' requires '@livekit/

Error message

@mastra/livekit: turnDetection '${kind}' requires '@livekit/agents-plugin-livekit'. Install it or use a built-in mode like 'vad' or 'stt'.

What it means

createLiveKitWorker's semantic turn detection modes ('multilingual' or 'english') require the '@livekit/agents-plugin-livekit' turn detector package, loaded via dynamic import. When the import fails, the worker throws and suggests installing the plugin or falling back to a built-in mode like 'vad' or 'stt'.

Source

Thrown at integrations/livekit/src/worker.ts:229

  let silero;
  try {
    silero = await import('@livekit/agents-plugin-silero');
  } catch (error) {
    throw new Error(
      "@mastra/livekit: voice activity detection requires '@livekit/agents-plugin-silero'. " +
        'Install it, pass your own `vad` instance, or set `vad: false`.',
      { cause: error },
    );
  }
  return silero.VAD.load();
}

async function loadTurnDetector(kind: 'multilingual' | 'english'): Promise<TurnDetectionSetting> {
  let plugin;
  try {
    plugin = await import('@livekit/agents-plugin-livekit');
  } catch (error) {
    throw new Error(
      `@mastra/livekit: turnDetection '${kind}' requires '@livekit/agents-plugin-livekit'. ` +
        "Install it or use a built-in mode like 'vad' or 'stt'.",
      { cause: error },
    );
  }
  return kind === 'english'
    ? (new plugin.turnDetector.EnglishModel() as TurnDetectionSetting)
    : (new plugin.turnDetector.MultilingualModel() as TurnDetectionSetting);
}

async function resolveMastraAgent(
  options: CreateLiveKitWorkerOptions,
  args: ResolveMastraAgentArgs,
): Promise<MastraAgent> {
  let ref: string | MastraAgent | undefined =
    typeof options.agent === 'function' ? await options.agent(args) : options.agent;
  ref ??= args.metadata.agentId;
  if (!ref) {

View on GitHub (pinned to 75dd419e61)

Solutions

Install @livekit/agents-plugin-livekit (pnpm add @livekit/agents-plugin-livekit).
Change turnDetection to a built-in mode: 'vad' or 'stt'.
Inspect the error's `cause` if the package is installed but the dynamic import still fails (bundler/resolution issues).

Example fix

// before
createLiveKitWorker({ mastra, workflow: 'voiceFlow', turnDetection: 'english' }); // plugin missing
// after
pnpm add @livekit/agents-plugin-livekit
createLiveKitWorker({ mastra, workflow: 'voiceFlow', turnDetection: 'english' });
// or
createLiveKitWorker({ mastra, workflow: 'voiceFlow', turnDetection: 'vad' });

Defensive patterns

Strategy: fallback

Validate before calling

let semanticTurnDetection = true;
try { await import('@livekit/agents-plugin-livekit'); } catch { semanticTurnDetection = false; }
if (!semanticTurnDetection && ['english', 'multilingual'].includes(options.turnDetection)) {
  console.warn('turn detector plugin missing; falling back to built-in mode');
}

Try / catch

let turnDetection = 'english';
try {
  await import('@livekit/agents-plugin-livekit');
} catch {
  turnDetection = 'vad'; // built-in fallback
}
createLiveKitWorker({ mastra, workflow: 'voiceFlow', turnDetection });

Prevention

Install @livekit/agents-plugin-livekit whenever using 'english'/'multilingual' turnDetection.
Probe plugin availability at worker startup and log the effective turn detection mode.
Prefer built-in 'vad'/'stt' modes when you want zero extra dependencies.

When it happens

Trigger: Setting turnDetection to 'multilingual' or 'english' in createLiveKitWorker options while @livekit/agents-plugin-livekit is not installed.

Common situations: Enabling semantic end-of-turn detection without adding the optional plugin dependency; pnpm strict installs omitting transitive deps; typo-free but unmet optional peer dependency after a dependency cleanup.

Related errors

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