remotion-dev/remotion · error · TypeError

Image format mismatch: ${outName} was given as the ${outName

Error message

Image format mismatch: ${outName} was given as the ${outNameDescription} and ${downloadName} was given as the download name, but the extensions don't match.

What it means

`determineFinalStillImageFormat` reconciles the format implied by the `outName` (file path or Lambda S3 key) with the format implied by the `downloadName`. If both filenames have recognizable extensions (png/jpeg/pdf/webp) and they differ, the function throws a TypeError because Remotion cannot pick which to honor for a still render.

Source

Thrown at packages/cli/src/determine-image-format.ts:59

	configuredImageFormat: StillImageFormat | null;
	isLambda: boolean;
	fromUi: StillImageFormat | null;
}): {format: StillImageFormat; source: string} => {
	if (fromUi) {
		return {format: fromUi, source: 'via UI'};
	}

	const outNameExtension = deriveExtensionFromFilename(outName);
	const downloadNameExtension = deriveExtensionFromFilename(downloadName);

	const outNameDescription = isLambda ? 'S3 output key' : 'out name';

	if (
		outNameExtension &&
		downloadNameExtension &&
		outNameExtension !== downloadNameExtension
	) {
		throw new TypeError(
			`Image format mismatch: ${outName} was given as the ${outNameDescription} and ${downloadName} was given as the download name, but the extensions don't match.`,
		);
	}

	if (downloadNameExtension) {
		if (
			configuredImageFormat &&
			downloadNameExtension !== configuredImageFormat
		) {
			throw new TypeError(
				`Image format mismatch: ${downloadName} was given as the download name, but the image format "${configuredImageFormat}" was configured via --${cliFlag} or Config.setStillImageFormat(). The image formats must match.`,
			);
		}

		return {format: downloadNameExtension, source: 'Download name extension'};
	}

	if (outNameExtension) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Make `outName` and `downloadName` end with the same extension.
2. Drop the extension from one side so it is inferred from the other.

Example fix

// before
$ remotion still src/index.ts myComp out.png --download-name=thumb.jpg
// after
$ remotion still src/index.ts myComp out.png --download-name=thumb.png

const outExt = outName.split('.').pop();
const dlExt = downloadName.split('.').pop();
if (outExt && dlExt && outExt.toLowerCase() !== dlExt.toLowerCase()) {
  throw new Error(`outName (${outExt}) and downloadName (${dlExt}) extensions must match`);
}

const extensionsAgree = (a: string, b: string): boolean => {
  const ext = (s: string) => s.split('.').pop()?.toLowerCase();
  const ea = ext(a), eb = ext(b);
  return !ea || !eb || ea === eb;
};

When it happens

Trigger: Calling `remotion still` with `--output=out.png` plus a `--download-name=thumb.jpg`, or a Lambda render where the S3 output key ends in `.png` but the requested download name ends in `.jpeg`. Both extensions must be recognized (png/jpg/jpeg/pdf/webp).

Common situations: Mixed config: pipeline that produces a PNG on S3 but downloads a JPEG locally; CI script templated with mismatched variables; copy-paste between a Lambda and local render invocation.

Related errors

• Image format mismatch: ${outName} was given as the ${outName
• Image format mismatch: ${downloadName} was given as the down
• Pass --s3-output-provider-endpoint when using S3 output prov
• Pass --force-bucket-name when using S3 output provider flags
• Pass --out-name when using S3 output provider flags.

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/892c6c00b581a564. Report an issue: GitHub.