remotion-dev/remotion · error

Unknown video matting model: ${modelName}.

Error message

Unknown video matting model: ${modelName}.

What it means

Thrown when `input.model` is a string but does not match any model name returned by @remotion/video-matting's getAvailableModels(). Only installed/supported models (e.g. 'ben2-base') are accepted; the message echoes the unknown name.

Source

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

							assetPath: input.assetPath,
							currentContent: currentContentRef.current,
							staticFiles: staticFilesRef.current,
						});
						if (getPreviewFileType(assetPath) !== 'video') {
							throw new Error('The separation asset must be a video.');
						}

						const videoMatting = await import('@remotion/video-matting');
						const modelName = input.model ?? 'ben2-base';
						if (typeof modelName !== 'string') {
							throw new Error('model must be a string.');
						}

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

						const audio = input.audio ?? 'base';
						if (
							audio !== 'base' &&
							audio !== 'foreground' &&
							audio !== 'both' &&
							audio !== 'none'
						) {
							throw new Error('audio must be base, foreground, both, or none.');
						}

						const videoBitrate = input.videoBitrate ?? 'very-high';
						if (
							(typeof videoBitrate !== 'number' ||
								!Number.isInteger(videoBitrate) ||
								videoBitrate <= 0) &&
							videoBitrate !== 'very-low' &&

View on GitHub (pinned to b2f4e34732)

Solutions

1. Use an exact name from getAvailableModels(), e.g. 'ben2-base'.
2. Update @remotion/video-matting to the latest version if the model should exist.
3. Omit input.model entirely to accept the default model.

Example fix

// before
{ model: 'ben2' }
// after
{ model: 'ben2-base' }

const names = videoMatting.getAvailableModels().map(m => m.name);
if (modelName != null && !names.includes(modelName)) throw new Error(`Pick one of: ${names.join(', ')}`);

try { await separate(input); } catch (e) { if (String(e.message).startsWith('Unknown video matting model')) { input.model = 'ben2-base'; } else throw e; }

When it happens

Trigger: Passing a string like 'ben2', 'BEN2-Base' (case-sensitive), a model from another library, or a model name valid in a newer/older @remotion/video-matting version.

Common situations: Typo'd or hallucinated model names from AI agents, case mismatch, or version drift where the requested model was renamed or not yet released.

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

• audio must be base, foreground, both, or none.
• The bitrate quality must be one of ${VIDEO_MATTING_QUALITIES
• "${name}" must be one of ${variants.join(', ')}
• Value for ${JSON.stringify(key)} must be one of ${Object.key
• The "${name}" prop ${location} must be one of ${validCodecs.

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