remotion-dev/remotion · error

Unknown Whisper model: ${modelName}.

Error message

Unknown Whisper model: ${modelName}.

What it means

This error is thrown by the WebMcp caption/transcription tool handler in Remotion Studio when the requested Whisper model name does not match any entry from getAvailableModels(). The library validates the `model` input against the known model catalog before starting a transcription job, and fails fast when the model cannot be resolved.

Source

Thrown at packages/studio/src/components/WebMcp.tsx:521

						});
						const fileType = getPreviewFileType(assetPath);
						if (fileType !== 'audio' && fileType !== 'video') {
							throw new Error(
								'The transcription asset must be audio or video.',
							);
						}

						const whisper = await import('@remotion/whisper-webgpu');
						const modelName = input.model ?? 'small.en';
						if (typeof modelName !== 'string') {
							throw new Error('model must be a string.');
						}

						const model = whisper
							.getAvailableModels()
							.find((candidate) => candidate.name === modelName);
						if (!model) {
							throw new Error(`Unknown Whisper model: ${modelName}.`);
						}

						const task = input.task ?? 'transcribe';
						if (task !== 'transcribe' && task !== 'translate') {
							throw new Error('task must be transcribe or translate.');
						}

						if (task === 'translate' && !model.supportsTranslation) {
							throw new Error(`${model.name} does not support translation.`);
						}

						const language = input.language ?? 'en';
						if (typeof language !== 'string' || language.length === 0) {
							throw new Error('language must be a non-empty string.');
						}

						const chunkLengthInSeconds = input.chunkLengthInSeconds ?? 30;
						const strideLengthInSeconds = input.strideLengthInSeconds ?? 5;

View on GitHub (pinned to b2f4e34732)

Solutions

  1. Call the tool with the list-models / equivalent query to get valid names from whisper.getAvailableModels() and use one exactly
  2. Use one of the known model names: tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3, etc., matching the catalog exactly
  3. Fix casing and remove any org prefix from the model name

Example fix

// before
{ "tool": "transcribe-captions", "input": { "model": "Xenova/whisper-tiny.en" } }
// after
{ "tool": "transcribe-captions", "input": { "model": "tiny.en" } }
Defensive patterns

Strategy: validation

Validate before calling

const validModels = whisper.getAvailableModels().map((m) => m.name);
if (!validModels.includes(input.model)) {
  throw new Error(`model must be one of: ${validModels.join(', ')}`);
}

Type guard

const isKnownModel = (name: string): boolean =>
  whisper.getAvailableModels().some((m) => m.name === name);

Try / catch

try {
  await callWhisperTool({ model: input.model });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown Whisper model')) {
    const names = whisper.getAvailableModels().map((m) => m.name);
    console.warn(`Bad model "${input.model}"; valid: ${names.join(', ')}`);
  }
}

Prevention

When it happens

Trigger: Calling the WebMcp whisper transcription tool with input.model set to a name that is not an exact match (case-sensitive) of one of whisper.getAvailableModels()' `name` fields, e.g. "whisper-tiny" vs "tiny", "Whisper-Tiny", or a typo.

Common situations: Hand-typing a model name into an MCP tool call instead of first listing available models; copying a HuggingFace model id like "Xenova/whisper-tiny.en" when the tool expects just "tiny.en"; casing mistakes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/2fd836dcb8dfa1bb. Report an issue: GitHub.