What causes "generate-image: --background requires a .png --out path. " in pbakaus/impeccable?

Change --out to a path ending in .png (e.g. --out assets/logo.png).

generate-image: --background requires a .png --out path.

Error message

generate-image: --background requires a .png --out path.

What it means

When `--background` is supplied to generate-image, the output path must end in `.png` because background handling (especially transparency) is only supported for the PNG format. The CLI rejects any other extension before making the API call.

Solutions

Change --out to a path ending in .png (e.g. --out assets/logo.png).
If PNG is not acceptable, drop the --background flag so the extension check is skipped.
Convert the resulting PNG to another format afterwards with an image tool if you need a smaller/other format.

Example fix

// before
generate-image --prompt "icon" --background transparent --out icon.webp
// after
generate-image --prompt "icon" --background transparent --out icon.png

Defensive patterns

Strategy: validation

Validate before calling

if (useBackground && !outPath.toLowerCase().endsWith('.png')) {
  throw new Error('--background requires a .png --out path');
}

Prevention

Pair --background with .png outputs by convention in your build scripts.
Remember transparency requires PNG; convert to other formats only after generation.
Validate the --out extension alongside the --background flag in the same pre-flight check.

When it happens

Trigger: Running `generate-image --prompt ... --background transparent --out image.jpg` (or `.webp`, `.jpeg`, or a path whose extension is not `.png`). The check is case-insensitive on the extension but requires the PNG suffix.

Common situations: Generating website assets as JPEG/WebP while also requesting a transparent background; forgetting that transparency forces PNG even though non-transparent generation allows other formats.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@f2c7051853 (2026-09-16). Data as JSON: /api/errors/f89d4d5460f27e1c. Report an issue: GitHub.

Appendix: source

Thrown at crates/context/src/generate_image.rs:260

            return (a.parse().unwrap_or(1536), b.parse().unwrap_or(1024));
        }
    }
    (1536, 1024)
}

pub fn run(args: &[String], io: &mut Io) -> i32 {
    run_with_api_base(args, io, "https://api.openai.com/v1")
}

fn run_with_api_base(args: &[String], io: &mut Io, api_base: &str) -> i32 {
    let background = arg(args, "background");
    if args.iter().any(|a| a == "--background") && !matches!(background.as_deref(), Some("transparent" | "opaque" | "auto")) {
        io.err("generate-image: --background must be transparent, opaque, or auto.\n");
        return 1;
    }
    let transparent = background.as_deref() == Some("transparent");
    if background.is_some() && arg(args, "out").is_some_and(|out| !out.to_ascii_lowercase().ends_with(".png")) {
        io.err("generate-image: --background requires a .png --out path.\n");
        return 1;
    }
    let cwd = io.cwd.to_string_lossy().into_owned();
    let env: Env = io.env.clone();
    let abs = |p: &str| jsp::resolve(&cwd, &[p]);
    let read_prompt_file = |io: &mut Io, pf: &str| -> Result<String, i32> {
        match std::fs::read(abs(pf)) {
            Ok(b) => Ok(String::from_utf8_lossy(&b).into_owned()),
            Err(e) => {
                io.err(&format!("Error: {}\n", node_read_error(pf, &e)));
                Err(1)
            }
        }
    };
    if env.get("IMPECCABLE_IMAGE_GEN_FAKE").map(|v| !v.is_empty()).unwrap_or(false) {
        let prompt = match arg(args, "prompt-file") {
            Some(pf) => match read_prompt_file(io, &pf) {
                Ok(p) => Some(p),

View on GitHub (pinned to f2c7051853)