{"record":{"id":"892c6c00b581a564","repo":"remotion-dev/remotion","slug":"image-format-mismatch-outname-was-given-as-the","errorCode":null,"errorMessage":"Image format mismatch: ${outName} was given as the ${outNameDescription} and ${downloadName} was given as the download name, but the extensions don't match.","messagePattern":"Image format mismatch: (.+?) was given as the (.+?) and (.+?) was given as the download name, but the extensions don't match\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/determine-image-format.ts","lineNumber":59,"sourceCode":"\tconfiguredImageFormat: StillImageFormat | null;\n\tisLambda: boolean;\n\tfromUi: StillImageFormat | null;\n}): {format: StillImageFormat; source: string} => {\n\tif (fromUi) {\n\t\treturn {format: fromUi, source: 'via UI'};\n\t}\n\n\tconst outNameExtension = deriveExtensionFromFilename(outName);\n\tconst downloadNameExtension = deriveExtensionFromFilename(downloadName);\n\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) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cli/src/determine-image-format.ts#L41-L77","documentation":"`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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Make `outName` and `downloadName` end with the same extension.","Drop the extension from one side so it is inferred from the other."],"exampleFix":"// before\n$ remotion still src/index.ts myComp out.png --download-name=thumb.jpg\n// after\n$ remotion still src/index.ts myComp out.png --download-name=thumb.png","handlingStrategy":"validation","validationCode":"const outExt = outName.split('.').pop();\nconst dlExt = downloadName.split('.').pop();\nif (outExt && dlExt && outExt.toLowerCase() !== dlExt.toLowerCase()) {\n  throw new Error(`outName (${outExt}) and downloadName (${dlExt}) extensions must match`);\n}","typeGuard":"const extensionsAgree = (a: string, b: string): boolean => {\n  const ext = (s: string) => s.split('.').pop()?.toLowerCase();\n  const ea = ext(a), eb = ext(b);\n  return !ea || !eb || ea === eb;\n};","tryCatchPattern":null,"preventionTips":["Template output and download names from a single extension variable.","Drop extensions on the name that should be inferred."],"tags":["still","image-format","validation","lambda","cli"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}