remotion-dev/remotion · error · TypeError

Image format mismatch: ${downloadName} was given as the down

Error message

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.

What it means

After reconciling the two filenames, `determineFinalStillImageFormat` checks the `downloadName` extension against the format configured via `--image-format` (CLI flag `stillImageFormatOption.cliFlag`) or `Config.setStillImageFormat()`. If both are set and they disagree, it throws a TypeError because the configured format overrides inference but cannot silently contradict a filename.

Source

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

	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) {
		if (configuredImageFormat && outNameExtension !== configuredImageFormat) {
			throw new TypeError(
				`Image format mismatch: ${outName} was given as the ${outNameDescription}, but the image format "${configuredImageFormat}" was configured via --${cliFlag} or Config.setStillImageFormat(). The image formats must match.`,
			);
		}

		return {format: outNameExtension, source: 'Out name extension'};
	}

	if (configuredImageFormat !== null) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Align the configured format with the filename extension (e.g. both `jpeg`).
Remove the explicit `--image-format` / `Config.setStillImageFormat()` call and let the filename drive the format.

Example fix

// before
$ remotion still src/index.ts myComp thumb.jpg --image-format=png
// after
$ remotion still src/index.ts myComp thumb.jpg --image-format=jpeg

Defensive patterns

Strategy: validation

Validate before calling

const dlExt = downloadName.split('.').pop()?.toLowerCase();
if (configuredFormat && dlExt && configuredFormat !== dlExt) {
  throw new Error(`downloadName extension (${dlExt}) must match configured format (${configuredFormat})`);
}

Type guard

const formatMatchesExtension = (format: string, filename: string): boolean => {
  const ext = filename.split('.').pop()?.toLowerCase();
  const extAsFormat = ext === 'jpg' ? 'jpeg' : ext;
  return !extAsFormat || format === extAsFormat;
};

Prevention

Either set the format explicitly or drive it from the filename — not both with conflicting values.
Keep `Config.setStillImageFormat()` calls in one place so they are easy to audit.

When it happens

Trigger: Running `remotion still ... --output=thumb.jpg --image-format=png`, or setting `Config.setStillImageFormat('png')` in config while the output filename ends in `.jpg`/`.jpeg`/`.pdf`/`.webp`.

Common situations: Stale `Config.setStillImageFormat()` from a previous pipeline; CI that hard-codes `--image-format` while templating the output filename separately; team convention changed format without updating scripts.

Related errors

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