{"record":{"id":"431a9e3968ea58d0","repo":"remotion-dev/remotion","slug":"image-format-mismatch-outname-was-given-as-the-431a9e","errorCode":null,"errorMessage":"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.","messagePattern":"Image format mismatch: (.+?) was given as the (.+?), but the image format \"(.+?)\" was configured via --(.+?) or Config\\.setStillImageFormat\\(\\)\\. The image formats must match\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/determine-image-format.ts","lineNumber":79,"sourceCode":"\t\t);\n\t}\n\n\tif (downloadNameExtension) {\n\t\tif (\n\t\t\tconfiguredImageFormat &&\n\t\t\tdownloadNameExtension !== configuredImageFormat\n\t\t) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`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.`,\n\t\t\t);\n\t\t}\n\n\t\treturn {format: downloadNameExtension, source: 'Download name extension'};\n\t}\n\n\tif (outNameExtension) {\n\t\tif (configuredImageFormat && outNameExtension !== configuredImageFormat) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`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.`,\n\t\t\t);\n\t\t}\n\n\t\treturn {format: outNameExtension, source: 'Out name extension'};\n\t}\n\n\tif (configuredImageFormat !== null) {\n\t\treturn {format: configuredImageFormat, source: `--${cliFlag} or config`};\n\t}\n\n\treturn {format: 'png', source: 'Default'};\n};\n","sourceCodeStart":61,"sourceCodeEnd":93,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cli/src/determine-image-format.ts#L61-L93","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Make the `outName`/S3 key extension match the configured format.","Drop the explicit `--image-format` / `Config.setStillImageFormat()` so the extension is inferred from `outName`."],"exampleFix":"// before\n$ remotion still src/index.ts myComp out.png --image-format=jpeg\n// after\n$ remotion still src/index.ts myComp out.jpg --image-format=jpeg","handlingStrategy":"validation","validationCode":"const outExt = outName.split('.').pop()?.toLowerCase();\nif (configuredFormat && outExt && configuredFormat !== (outExt === 'jpg' ? 'jpeg' : outExt)) {\n  throw new Error(`outName extension (${outExt}) must match configured format (${configuredFormat})`);\n}","typeGuard":"const formatMatchesExtension = (format: string, filename: string): boolean => {\n  const ext = filename.split('.').pop()?.toLowerCase();\n  const extAsFormat = ext === 'jpg' ? 'jpeg' : ext;\n  return !extAsFormat || format === extAsFormat;\n};","tryCatchPattern":null,"preventionTips":["For Lambda, drive the S3 key extension from the same constant as the configured format.","Audit render/still scripts after any format change so filenames stay in sync."],"tags":["still","image-format","validation","cli","config","lambda"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}