pbakaus/impeccable · error

comp-spec: --background must be transparent, opaque, or…

Error message

comp-spec: --background must be transparent, opaque, or auto.

What it means

comp-spec validates the optional `--background` flag when a `plate-prompt` is requested and rejects any value other than `transparent`, `opaque`, or `auto`. The flag is only checked when `--background` is present (or with a bare value), so the message means the CLI received a `--background` argument with an unsupported value or no recognized value.

Solutions

1. Set --background to exactly one of: transparent, opaque, or auto (e.g. `comp-spec --plate-prompt --background transparent`).
2. If you do not need a specific background, omit the --background flag entirely and let the default (auto) apply.
3. Check spelling/case: values are lowercase with no extra whitespace or `=`-quoting issues.

Example fix

// before
comp-spec --plate-prompt --background alpha
// after
comp-spec --plate-prompt --background transparent

const ALLOWED = new Set(['transparent', 'opaque', 'auto']);
if (process.argv.includes('--background')) {
  const v = process.argv[process.argv.indexOf('--background') + 1];
  if (!ALLOWED.has(v)) throw new Error(`--background must be transparent, opaque, or auto (got: ${v})`);
}

When it happens

Trigger: Running `impeccable comp-spec --plate-prompt` with `--background` set to a typo'd or out-of-enum value (e.g. `--background=alpha`, `--background clear`), or passing a bare `--background` with no value so `arg(argv, "background")` returns something other than the three allowed strings.

Common situations: Copy-pasting flag values from another image tool (e.g. `rgba`, `none`), assuming background accepts free-form color names, or forgetting that only three enum values are accepted for plate prompts.

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

• Available commands
• build-phase: finish --disposition…
• comp-spec: cannot read regions
• embed-prompt: malformed PNG
• Error: --scope requires a value. Valid scopes

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

Appendix: source

Thrown at crates/comp-verbs/src/comp_spec.rs:822

/// `impeccable comp-spec ...`
pub fn run(argv: &[String], io: &mut Io) -> i32 {
    let spec_path = arg_or(argv, "spec", SPEC_PATH).to_string();
    if flag(argv, "help") || argv.is_empty() {
        io.out("usage: comp-spec.mjs --comp <png> --grid            write .impeccable/build/comp-grid.png (10x10 labeled grid) + palette + bands\n       comp-spec.mjs --comp <png> --regions <json>  measure regions -> .impeccable/build/spec.json\n         regions json: { \"regions\": [ { \"id\": \"art\", \"kind\": \"plate|image|texture|text|control|chrome\", \"grid\": \"E0:J4\", \"note\": \"...\" } ] }\n       comp-spec.mjs --comp <png> --auto            band regions when you have no regions file\n       comp-spec.mjs --print                        the compact spec\n       comp-spec.mjs --crop <id> [--out f] [--scale n]   reference crop of a region (never a shipping asset)\n       comp-spec.mjs --plate-prompt <id> [--background transparent|opaque|auto]  the regeneration prompt for a raster region\n");
        return 0;
    }
    if flag(argv, "print") {
        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {
            io.err(&format!("comp-spec: no spec at {spec_path}; run with --comp <png> --regions <json> first\n"));
            return 1;
        };
        io.out(&format!("{}\n", print_spec(&spec)));
        return 0;
    }
    if let Some(id) = arg(argv, "plate-prompt") {
        let background = arg(argv, "background");
        if flag(argv, "background") && !matches!(background, Some("transparent" | "opaque" | "auto")) {
            io.err("comp-spec: --background must be transparent, opaque, or auto.\n");
            return 1;
        }
        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {
            io.err(&format!("comp-spec: no spec at {spec_path}\n"));
            return 1;
        };
        let region = spec.get("regions").and_then(Value::as_array).and_then(|a| a.iter().find(|r| r.get("id").and_then(Value::as_str) == Some(id)));
        let Some(region) = region else {
            io.err(&format!("comp-spec: no region {id}\n"));
            return 1;
        };
        io.out(&format!("{}\n", plate_prompt_background(&spec, region, background == Some("transparent"))));
        return 0;
    }
    if let Some(id) = arg(argv, "crop") {
        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {
            io.err(&format!("comp-spec: no spec at {spec_path}\n"));
            return 1;

View on GitHub (pinned to f2c7051853)