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.
Solutions
- Give the two outputs distinct names, e.g. 'clip-base.webm' and 'clip-foreground.webm'.
- Omit both paths so the defaults ('<name>-base.webm' / '<name>-foreground.webm') are used.
- 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' } Defensive patterns
Strategy: validation
Validate before calling
if (base.toLowerCase() === foreground.toLowerCase()) throw new Error('outputs must differ'); Prevention
- Derive foreground names by appending '-foreground' before the extension.
- Compare final names case-insensitively before submitting.
- Rely on defaults when custom names are not needed.
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.
Understand the failure class
Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.
Related errors
- A numeric bitrate must be a positive integer.
- audio must be base, foreground, both, or none.
- The bitrate quality must be one of
- The separation asset must be a video.
- The video frame duration must be non-negative.
AI-assisted analysis of remotion-dev/remotion@46a3a6bf13 (2026-09-09).
Data as JSON: /api/errors/5737850c551ec060.
Report an issue: GitHub.
Appendix: source
Thrown at packages/studio/src/components/WebMcp.tsx:768
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 46a3a6bf13)