--background-output is not supported for image inputs. Use a

Error message

--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.

What it means

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.

Source

Thrown at packages/cli/src/background-removal/pipeline.ts:254

): RenderTargets {
  const format = inferOutputFormat(outputPath);
  const inputKind = inferInputKind(inputPath);

  if (inputKind === "image" && format !== "png") {
    throw new Error(
      `Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.`,
    );
  }
  if (inputKind === "video" && format === "png") {
    throw new Error(
      `Video input requires a .webm or .mov output (got .png). Use an image input for .png.`,
    );
  }

  let bgFormat: OutputFormat | undefined;
  if (backgroundOutputPath) {
    if (inputKind === "image") {
      throw new Error(
        "--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.",
      );
    }
    bgFormat = inferOutputFormat(backgroundOutputPath);
    if (bgFormat === "png") {
      throw new Error(
        "--background-output must be .webm or .mov; .png is only valid for single-image inputs.",
      );
    }
  }

  return { format, inputKind, bgFormat };
}

export async function render(options: RenderOptions): Promise<RenderResult> {
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath || !findFFprobe()) {
    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);

View on GitHub (pinned to c2996c8626)

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'.

Example fix

// before
await render({
  inputPath: 'photo.png',
  outputPath: 'photo.png',
  backgroundOutputPath: 'bg.webm', // rejected
});
// after
await render({ inputPath: 'photo.png', outputPath: 'photo.png' });

Defensive patterns

Strategy: validation

Validate before calling

function resolveBgOption(inputPath: string, bgPath: string | undefined): string | undefined {
  const inExt = extname(inputPath).toLowerCase();
  const isImage = ['.jpg','.jpeg','.png','.webp'].includes(inExt);
  if (isImage) return undefined; // strip backgroundOutputPath for images
  return bgPath;
}
await render({ ...options, backgroundOutputPath: resolveBgOption(options.inputPath, options.backgroundOutputPath) });

Type guard

function bgSupportedForInput(inputPath: string): boolean {
  const isVideo = ['.mp4','.mov','.webm','.mkv','.avi'].includes(extname(inputPath).toLowerCase());
  return isVideo;
}

Prevention

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.

When it happens

Trigger: Calling render({ inputPath: 'photo.png', outputPath: 'out.png', backgroundOutputPath: 'bg.webm' }) — any image input plus a non-undefined backgroundOutputPath.

Common situations: 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.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/57496d34acec5867. Report an issue: GitHub.