Image input requires a .png output (got ${extname(outputPath

Error message

Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.

What it means

Thrown by resolveRenderTargets() when an image input (jpg/png/webp) is paired with a non-.png output. The pipeline only produces a single RGBA still for image inputs (encoded as PNG with alpha); video-container outputs like .webm/.mov require a frame sequence, which a single image cannot supply. This guard runs before any ffmpeg I/O.

Source

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

  format: OutputFormat;
  inputKind: "video" | "image";
  bgFormat: OutputFormat | undefined;
}

/**
 * Resolve and validate the input/output combination before any I/O. Pure;
 * exported so unit tests can pin the error messages without spawning ffmpeg.
 */
export function resolveRenderTargets(
  inputPath: string,
  outputPath: string,
  backgroundOutputPath?: string,
): 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") {

View on GitHub (pinned to c2996c8626)

Solutions

Change the output path to .png when the input is a single image: `out.png`.
If you need a .webm/.mov result, supply a video input (mp4/mov/webm/mkv/avi) instead of a still.
In a shared pipeline, branch on input kind before choosing the output extension.

Example fix

// before
await render({ inputPath: 'product.jpg', outputPath: 'product.webm' });
// after
await render({ inputPath: 'product.jpg', outputPath: 'product.png' });

Defensive patterns

Strategy: validation

Validate before calling

import { extname } from 'node:path';
function pickOutputExtForInput(input: string, desired: string): string {
  const inExt = extname(input).toLowerCase();
  const isImage = ['.jpg','.jpeg','.png','.webp'].includes(inExt);
  if (isImage) return '.png';
  return desired;
}
const outputPath = replaceExt(options.outputPath, pickOutputExtForInput(options.inputPath, '.webm'));
await render({ ...options, outputPath });

Type guard

function imageInputNeedsPng(inputPath: string, outputPath: string): boolean {
  const inExt = extname(inputPath).toLowerCase();
  const isImage = ['.jpg','.jpeg','.png','.webp'].includes(inExt);
  const outExt = extname(outputPath).toLowerCase();
  return isImage && outExt !== '.png';
}

Prevention

Choose the output extension based on input kind: image → .png, video → .webm/.mov.
In shared pipelines, branch on inferInputKind before assigning outputPath.
Write a unit test that pins the (image, non-png) rejection like the library's own tests do.

When it happens

Trigger: Calling render({ inputPath: 'subject.jpg', outputPath: 'cutout.webm' }) or any image input with a .webm/.mov output. resolveRenderTargets() calls inferInputKind then checks the (image, format!==png) combination.

Common situations: User records a static product photo and asks for a transparent .webm; copy-paste of a video-oriented output path for an image job; scripted pipeline that reuses one output template for both image and video inputs.

Related errors

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