remotion-dev/remotion · error

The separation asset must be a video.

Error message

The separation asset must be a video.

What it means

Thrown by the Remotion Studio WebMcp video-matting tool when the asset resolved from `input.assetPath` is not a video file. Before starting background/foreground separation, the Studio resolves the asset path against current content and static files and checks its preview file type via getPreviewFileType; only 'video' assets can be matted. Images, audio, or unresolvable paths fail this check.

Source

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

								],
								default: 'very-high',
							},
						},
						additionalProperties: false,
					},
					annotations: {readOnlyHint: false},
					execute: async (input) => {
						if (!isOptionalPackageInstalled(VIDEO_MATTING_PACKAGE)) {
							return missingOptionalPackageResult(VIDEO_MATTING_PACKAGE);
						}

						const assetPath = resolveAssetPath({
							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' &&

View on GitHub (pinned to b2f4e34732)

Solutions

1. Point input.assetPath at an actual video file (mp4/webm) inside the public folder.
2. Verify the resolved path with staticFile() and check its extension/type before invoking the tool.
3. Ensure the file exists and is included in Remotion static files so getPreviewFileType classifies it as video.

Example fix

// before
{ assetPath: 'poster.png' }
// after
{ assetPath: 'clips/interview.mp4' }

const isVideo = /\.(mp4|webm|mov|mkv|m4v)$/i.test(assetPath);
if (!isVideo) throw new Error('Provide a video asset for separation.');

const isVideoAsset = (p: string): boolean => /\.(mp4|webm|mov|mkv|m4v)$/i.test(p);

When it happens

Trigger: Calling the Studio WebMcp separation tool with input.assetPath pointing to a non-video static file (image, audio, JSON), or to a path that resolves to a file whose detected type is not 'video'.

Common situations: Passing a public/ image or audio file by mistake, passing a path relative to the wrong directory so resolution lands on an unexpected file, or expecting GIF/WebM variants to be classified as video when they are not.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Unknown video matting model: ${modelName}.
• audio must be base, foreground, both, or none.
• videoBitrate is invalid.
• Background and foreground outputs must be different.
• The video matting model returned invalid dimensions.

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