generate-image: OPENAI_API_KEY is not set; use the harness-n

Error message

generate-image: OPENAI_API_KEY is not set; use the harness-native image tool instead.

What it means

The generate-image command requires an OpenAI API key to perform a real image generation. If the OPENAI_API_KEY environment variable is unset or empty and the request did not opt into fake mode, the command refuses to run and exits 1, advising the user to use the harness-native image tool instead.

Source

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

            },
            None => arg(args, "prompt"),
        };
        let out = arg(args, "out");
        let (Some(prompt), Some(out)) = (prompt.filter(|p| !p.is_empty()), out) else {
            io.err("generate-image: --prompt (or --prompt-file) and --out are required.\n");
            return 1;
        };
        let (w, h) = parse_size(&arg(args, "size").unwrap_or_else(|| "1536x1024".into()));
        let bytes = if out.ends_with(".svg") { svg_fake(&prompt, w as f64, h as f64).into_bytes() } else { png_fake(&prompt, w, h) };
        if let Err(e) = std::fs::write(abs(&out), bytes) {
            io.err(&format!("Error: {}\n", node_read_error(&out, &e)));
            return 1;
        }
        io.out(&format!("IMAGE: {} ({}x{}, fake synthetic comp, $0.00, no API call)\n", out, w, h));
        return 0;
    }
    let Some(key) = env.get("OPENAI_API_KEY").filter(|k| !k.is_empty()).cloned() else {
        io.err("generate-image: OPENAI_API_KEY is not set; use the harness-native image tool instead.\n");
        return 1;
    };
    let prompt = match arg(args, "prompt-file") {
        Some(pf) => match read_prompt_file(io, &pf) {
            Ok(p) => Some(p),
            Err(c) => return c,
        },
        None => arg(args, "prompt"),
    };
    let out = arg(args, "out");
    let (Some(prompt), Some(out)) = (prompt.filter(|p| !p.is_empty()), out) else {
        io.err("generate-image: --prompt (or --prompt-file) and --out are required.\n");
        return 1;
    };
    let size = arg(args, "size").unwrap_or_else(|| "1536x1024".into());
    let quality = arg(args, "quality").unwrap_or_else(|| "medium".into());
    let mut refs: Vec<String> = Vec::new();
    for i in 0..args.len() {

View on GitHub (pinned to 2bc2879276)

Solutions

Set OPENAI_API_KEY in the environment: `export OPENAI_API_KEY=sk-...` before running the command.
Add the key to your CI secrets / .env loader so it is present in the subprocess environment.
If you only need a placeholder image (fake mode), use the flag/code path that triggers the synthetic generator instead of the API path.
As the message suggests, use your agent harness's native image tool when no OpenAI key is available.
Verify with `echo ${OPENAI_API_KEY:+set}` (or printenv) that the variable is actually visible to the process.

Example fix

// before
$ impeccable generate-image --prompt "sunset" --out sunset.png
// generate-image: OPENAI_API_KEY is not set...
// after
$ export OPENAI_API_KEY=sk-...
$ impeccable generate-image --prompt "sunset" --out sunset.png

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.OPENAI_API_KEY) {
  throw new Error("OPENAI_API_KEY must be set before running impeccable generate-image");
}
// or use the harness-native image tool as a fallback

Try / catch

try {
  execSync("impeccable generate-image --prompt ... --out ...", { stdio: "inherit", env: process.env });
} catch (e) {
  if (e.stderr.includes("OPENAI_API_KEY is not set")) {
    console.warn("falling back to harness-native image tool");
  } else throw e;
}

Prevention

Export OPENAI_API_KEY in shell profiles and CI secrets, not just .env files that CLIs may not load.
Verify env vars are exported (`export`, not plain assignment).
Check key presence with a preflight `printenv OPENAI_API_KEY` in scripts.
Use the fake/synthetic mode deliberately when no key is intended.

When it happens

Trigger: Calling `impeccable generate-image` with --prompt/--prompt-file and --out while `env.get("OPENAI_API_KEY")` returns None or an empty string — i.e. the variable is unset, set to empty, or not exported in the current shell/CI environment.

Common situations: Fresh machine or CI runner where the key was never configured; key defined in a shell profile but not exported; using a tool runner (dotenv not loaded) that strips environment variables; after rotating keys and removing the old one.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/570d47715891df3b. Report an issue: GitHub.