{"record":{"id":"d9b10d2670316ee5","repo":"remotion-dev/remotion","slug":"image-format-mismatch-downloadname-was-given-a","errorCode":null,"errorMessage":"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.","messagePattern":"Image format mismatch: (.+?) was given as the download name, 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":69,"sourceCode":"\n\tconst outNameDescription = isLambda ? 'S3 output key' : 'out name';\n\n\tif (\n\t\toutNameExtension &&\n\t\tdownloadNameExtension &&\n\t\toutNameExtension !== downloadNameExtension\n\t) {\n\t\tthrow new TypeError(\n\t\t\t`Image format mismatch: ${outName} was given as the ${outNameDescription} and ${downloadName} was given as the download name, but the extensions don't match.`,\n\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) {","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cli/src/determine-image-format.ts#L51-L87","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","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."],"exampleFix":"// before\n$ remotion still src/index.ts myComp thumb.jpg --image-format=png\n// after\n$ remotion still src/index.ts myComp thumb.jpg --image-format=jpeg","handlingStrategy":"validation","validationCode":"const dlExt = downloadName.split('.').pop()?.toLowerCase();\nif (configuredFormat && dlExt && configuredFormat !== dlExt) {\n  throw new Error(`downloadName extension (${dlExt}) 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":["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."],"tags":["still","image-format","validation","cli","config"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}