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}, but the image format "${configuredImageFormat}" was configured via --${cliFlag} or Config.setStillImageFormat(). The image formats must match.

What it means

Symmetric to the download-name check: if only the `outName` has a recognizable extension and it disagrees with the format set via `--image-format`/`Config.setStillImageFormat()`, `determineFinalStillImageFormat` throws a TypeError. For Lambda the outName is described as the 'S3 output key' in the message.

Source

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

		);
	}

	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) {
		return {format: configuredImageFormat, source: `--${cliFlag} or config`};
	}

	return {format: 'png', source: 'Default'};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Make the `outName`/S3 key extension match the configured format.
2. Drop the explicit `--image-format` / `Config.setStillImageFormat()` so the extension is inferred from `outName`.

Example fix

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

const outExt = outName.split('.').pop()?.toLowerCase();
if (configuredFormat && outExt && configuredFormat !== (outExt === 'jpg' ? 'jpeg' : outExt)) {
  throw new Error(`outName extension (${outExt}) must match configured format (${configuredFormat})`);
}

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

When it happens

Trigger: Running `remotion still ... --output=out.png --image-format=jpeg`, or a Lambda render where the S3 key ends in `.png` but `Config.setStillImageFormat('jpeg')` is set (or `--image-format=jpeg` was passed).

Common situations: Lambda template that always appends `.png` to the S3 key but a config that sets JPEG; CI that hard-codes `--image-format` regardless of the templated output path; refactor that renamed output files but left the format flag in place.

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/431a9e3968ea58d0. Report an issue: GitHub.