{"record":{"id":"f89d4d5460f27e1c","repo":"pbakaus/impeccable","slug":"generate-image-background-requires-a-png-out-path","errorCode":null,"errorMessage":"generate-image: --background requires a .png --out path.\n","messagePattern":"generate-image: --background requires a \\.png --out path\\.\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/generate_image.rs","lineNumber":260,"sourceCode":"            return (a.parse().unwrap_or(1536), b.parse().unwrap_or(1024));\n        }\n    }\n    (1536, 1024)\n}\n\npub fn run(args: &[String], io: &mut Io) -> i32 {\n    run_with_api_base(args, io, \"https://api.openai.com/v1\")\n}\n\nfn run_with_api_base(args: &[String], io: &mut Io, api_base: &str) -> i32 {\n    let background = arg(args, \"background\");\n    if args.iter().any(|a| a == \"--background\") && !matches!(background.as_deref(), Some(\"transparent\" | \"opaque\" | \"auto\")) {\n        io.err(\"generate-image: --background must be transparent, opaque, or auto.\\n\");\n        return 1;\n    }\n    let transparent = background.as_deref() == Some(\"transparent\");\n    if background.is_some() && arg(args, \"out\").is_some_and(|out| !out.to_ascii_lowercase().ends_with(\".png\")) {\n        io.err(\"generate-image: --background requires a .png --out path.\\n\");\n        return 1;\n    }\n    let cwd = io.cwd.to_string_lossy().into_owned();\n    let env: Env = io.env.clone();\n    let abs = |p: &str| jsp::resolve(&cwd, &[p]);\n    let read_prompt_file = |io: &mut Io, pf: &str| -> Result<String, i32> {\n        match std::fs::read(abs(pf)) {\n            Ok(b) => Ok(String::from_utf8_lossy(&b).into_owned()),\n            Err(e) => {\n                io.err(&format!(\"Error: {}\\n\", node_read_error(pf, &e)));\n                Err(1)\n            }\n        }\n    };\n    if env.get(\"IMPECCABLE_IMAGE_GEN_FAKE\").map(|v| !v.is_empty()).unwrap_or(false) {\n        let prompt = match arg(args, \"prompt-file\") {\n            Some(pf) => match read_prompt_file(io, &pf) {\n                Ok(p) => Some(p),","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/pbakaus/impeccable/blob/f2c7051853848826aac2f4646581d62a732155ad/crates/context/src/generate_image.rs#L242-L278","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ngenerate-image --prompt \"icon\" --background transparent --out icon.webp\n// after\ngenerate-image --prompt \"icon\" --background transparent --out icon.png","handlingStrategy":"validation","validationCode":"if (useBackground && !outPath.toLowerCase().endsWith('.png')) {\n  throw new Error('--background requires a .png --out path');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["cli","validation","png"],"backgroundTag":"conflicting-config-options","analyzedSha":"f2c7051853848826aac2f4646581d62a732155ad","analyzedAt":"2026-09-16T20:43:47.549Z","contentChangedAt":"2026-09-16T20:43:47.549Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}