{"record":{"id":"57496d34acec5867","repo":"heygen-com/hyperframes","slug":"background-output-is-not-supported-for-image-inp","errorCode":null,"errorMessage":"--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.","messagePattern":"--background-output is not supported for image inputs\\. Use a video input \\(mp4/mov/webm\\) to produce both a cutout and a background plate\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/background-removal/pipeline.ts","lineNumber":254,"sourceCode":"): RenderTargets {\n  const format = inferOutputFormat(outputPath);\n  const inputKind = inferInputKind(inputPath);\n\n  if (inputKind === \"image\" && format !== \"png\") {\n    throw new Error(\n      `Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.`,\n    );\n  }\n  if (inputKind === \"video\" && format === \"png\") {\n    throw new Error(\n      `Video input requires a .webm or .mov output (got .png). Use an image input for .png.`,\n    );\n  }\n\n  let bgFormat: OutputFormat | undefined;\n  if (backgroundOutputPath) {\n    if (inputKind === \"image\") {\n      throw new Error(\n        \"--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.\",\n      );\n    }\n    bgFormat = inferOutputFormat(backgroundOutputPath);\n    if (bgFormat === \"png\") {\n      throw new Error(\n        \"--background-output must be .webm or .mov; .png is only valid for single-image inputs.\",\n      );\n    }\n  }\n\n  return { format, inputKind, bgFormat };\n}\n\nexport async function render(options: RenderOptions): Promise<RenderResult> {\n  const ffmpegPath = findFFmpeg();\n  if (!ffmpegPath || !findFFprobe()) {\n    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/pipeline.ts#L236-L272","documentation":"Thrown by resolveRenderTargets() when backgroundOutputPath is supplied AND the input is an image. The background plate (inverse-alpha hole-cut) is only meaningful for a sequence of frames — it encodes the scene behind a moving subject over time. For a single still there is no temporal background to recover, so the option is rejected as a user error rather than silently ignored.","triggerScenarios":"Calling render({ inputPath: 'photo.png', outputPath: 'out.png', backgroundOutputPath: 'bg.webm' }) — any image input plus a non-undefined backgroundOutputPath.","commonSituations":"User reuses a video-oriented command template (that includes --background-output) against a single product photo; scripted batch job that always sets the background path; misunderstanding that the plate feature is video-only.","solutions":["Drop the backgroundOutputPath option when the input is a single image.","Switch to a video input (mp4/mov/webm/mkv/avi) to use the background-plate feature.","In shared code, only set backgroundOutputPath when inferInputKind(inputPath) === 'video'."],"exampleFix":"// before\nawait render({\n  inputPath: 'photo.png',\n  outputPath: 'photo.png',\n  backgroundOutputPath: 'bg.webm', // rejected\n});\n// after\nawait render({ inputPath: 'photo.png', outputPath: 'photo.png' });","handlingStrategy":"validation","validationCode":"function resolveBgOption(inputPath: string, bgPath: string | undefined): string | undefined {\n  const inExt = extname(inputPath).toLowerCase();\n  const isImage = ['.jpg','.jpeg','.png','.webp'].includes(inExt);\n  if (isImage) return undefined; // strip backgroundOutputPath for images\n  return bgPath;\n}\nawait render({ ...options, backgroundOutputPath: resolveBgOption(options.inputPath, options.backgroundOutputPath) });","typeGuard":"function bgSupportedForInput(inputPath: string): boolean {\n  const isVideo = ['.mp4','.mov','.webm','.mkv','.avi'].includes(extname(inputPath).toLowerCase());\n  return isVideo;\n}","tryCatchPattern":null,"preventionTips":["Only set backgroundOutputPath when the input is a video.","Document the video-only nature of the background-plate feature in your CLI wrapper.","Strip the option in batch jobs that mix image and video inputs."],"tags":["validation","background-removal","option-misuse","pre-io"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}