remotion-dev/remotion · error · Error

Background and foreground outputs must be different.

Error message

Background and foreground outputs must be different.

What it means

Thrown when the background and foreground output names are identical after NFC normalization and lowercasing. The two separation outputs must target distinct files, otherwise one would overwrite the other.

Source

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

						const baseError = validatePublicOutputName({
							extension: '.webm',
							outName: baseOutputPath,
						});
						const foregroundError = validatePublicOutputName({
							extension: '.webm',
							outName: foregroundOutputPath,
						});
						if (baseError !== null || foregroundError !== null) {
							throw new Error(
								baseError ?? foregroundError ?? 'Invalid output path.',
							);
						}

						if (
							baseOutputPath.normalize('NFC').toLowerCase() ===
							foregroundOutputPath.normalize('NFC').toLowerCase()
						) {
							throw new Error(
								'Background and foreground outputs must be different.',
							);
						}

						const jobId = addVideoMattingJob({
							audio,
							baseOutName: baseOutputPath,
							displayName,
							foregroundOutName: foregroundOutputPath,
							model,
							src,
							videoBitrate,
						});
						return {
							baseOutputPath,
							foregroundOutputPath,
							jobId,
							success: true,

View on GitHub (pinned to b2f4e34732)

Solutions

1. Give the two outputs distinct names, e.g. 'clip-base.webm' and 'clip-foreground.webm'.
2. Omit both paths so the defaults ('<name>-base.webm' / '<name>-foreground.webm') are used.
3. Ensure any suffix inserted differs between the two names regardless of case.

Example fix

// before
{ baseOutputPath: 'clip.webm', foregroundOutputPath: 'clip.webm' }
// after
{ baseOutputPath: 'clip-base.webm', foregroundOutputPath: 'clip-foreground.webm' }

if (base.toLowerCase() === foreground.toLowerCase()) throw new Error('outputs must differ');

When it happens

Trigger: Passing baseOutputPath and foregroundOutputPath with the same name, or names differing only by case/Unicode normalization (e.g. 'Out.webm' vs 'out.webm').

Common situations: Programmatically deriving both names from one template and forgetting the -base/-foreground suffix, or expecting case-insensitive filesystems to disambiguate.

Related errors

• The separation asset must be a video.
• Unknown video matting model: ${modelName}.
• audio must be base, foreground, both, or none.
• videoBitrate is invalid.
• The video matting model returned invalid dimensions.

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