generate-image: --background must be transparent, opaque…

Error message

generate-image: --background must be transparent, opaque, or auto.

What it means

generate-image checks that any `--background` argument carries one of the three supported values (`transparent`, `opaque`, `auto`) before calling the OpenAI image API. This early guard exits with status 1 rather than sending an invalid parameter upstream.

Solutions

Use one of the three accepted values: `--background transparent`, `--background opaque`, or `--background auto`.
Remove --background if you don't need background control.
In scripts, validate the shell variable before interpolation (e.g. only pass the flag when the value is in the allowed set).

Example fix

// before
generate-image --prompt "logo" --background alpha --out logo.png
// after
generate-image --prompt "logo" --background transparent --out logo.png

Defensive patterns

Strategy: validation

Validate before calling

const args = process.argv.slice(2);
const i = args.indexOf('--background');
if (i !== -1 && !['transparent', 'opaque', 'auto'].includes(args[i + 1])) {
  throw new Error(`--background must be transparent, opaque, or auto (got: ${args[i + 1]})`);
}

Type guard

const isBackgroundValue = (v) => v === 'transparent' || v === 'opaque' || v === 'auto';

Prevention

Use a whitelist type guard on background values before spawning the CLI.
Watch for empty variables in shell interpolation ("--background $BG" with BG unset).
Quote and normalize flag values to lowercase before passing them.

When it happens

Trigger: Invoking `generate-image ... --background <bad-value>` (e.g. `--background yes`, `--background None`), or passing `--background` with an empty/whitespace value so the value fails the `matches!("transparent" | "opaque" | "auto")` check.

Common situations: Scripting the CLI with a variable that is empty or holds an unexpected value, migrating from another generator whose background flag took different values, or typos like `trasparent`.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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

Appendix: source

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

}

fn parse_size(s: &str) -> (usize, usize) {
    if let Some((a, b)) = s.split_once('x') {
        if !a.is_empty() && !b.is_empty() && a.chars().all(|c| c.is_ascii_digit()) && b.chars().all(|c| c.is_ascii_digit()) {
            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)
            }
        }

View on GitHub (pinned to f2c7051853)