{"record":{"id":"ba8fad3f6d7ee249","repo":"pbakaus/impeccable","slug":"comp-spec-background-must-be-transparent-opaque-or-auto","errorCode":null,"errorMessage":"comp-spec: --background must be transparent, opaque, or auto.\n","messagePattern":"comp-spec: --background must be transparent, opaque, or auto\\.\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/comp-verbs/src/comp_spec.rs","lineNumber":822,"sourceCode":"/// `impeccable comp-spec ...`\npub fn run(argv: &[String], io: &mut Io) -> i32 {\n    let spec_path = arg_or(argv, \"spec\", SPEC_PATH).to_string();\n    if flag(argv, \"help\") || argv.is_empty() {\n        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\");\n        return 0;\n    }\n    if flag(argv, \"print\") {\n        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {\n            io.err(&format!(\"comp-spec: no spec at {spec_path}; run with --comp <png> --regions <json> first\\n\"));\n            return 1;\n        };\n        io.out(&format!(\"{}\\n\", print_spec(&spec)));\n        return 0;\n    }\n    if let Some(id) = arg(argv, \"plate-prompt\") {\n        let background = arg(argv, \"background\");\n        if flag(argv, \"background\") && !matches!(background, Some(\"transparent\" | \"opaque\" | \"auto\")) {\n            io.err(\"comp-spec: --background must be transparent, opaque, or auto.\\n\");\n            return 1;\n        }\n        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {\n            io.err(&format!(\"comp-spec: no spec at {spec_path}\\n\"));\n            return 1;\n        };\n        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)));\n        let Some(region) = region else {\n            io.err(&format!(\"comp-spec: no region {id}\\n\"));\n            return 1;\n        };\n        io.out(&format!(\"{}\\n\", plate_prompt_background(&spec, region, background == Some(\"transparent\"))));\n        return 0;\n    }\n    if let Some(id) = arg(argv, \"crop\") {\n        let Some(spec) = load_spec(&resolve(io, &spec_path)) else {\n            io.err(&format!(\"comp-spec: no spec at {spec_path}\\n\"));\n            return 1;","sourceCodeStart":804,"sourceCodeEnd":840,"githubUrl":"https://github.com/pbakaus/impeccable/blob/f2c7051853848826aac2f4646581d62a732155ad/crates/comp-verbs/src/comp_spec.rs#L804-L840","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --background to exactly one of: transparent, opaque, or auto (e.g. `comp-spec --plate-prompt --background transparent`).","If you do not need a specific background, omit the --background flag entirely and let the default (auto) apply.","Check spelling/case: values are lowercase with no extra whitespace or `=`-quoting issues."],"exampleFix":"// before\ncomp-spec --plate-prompt --background alpha\n// after\ncomp-spec --plate-prompt --background transparent","handlingStrategy":"validation","validationCode":"const ALLOWED = new Set(['transparent', 'opaque', 'auto']);\nif (process.argv.includes('--background')) {\n  const v = process.argv[process.argv.indexOf('--background') + 1];\n  if (!ALLOWED.has(v)) throw new Error(`--background must be transparent, opaque, or auto (got: ${v})`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Memorize/centralize the three allowed values (transparent, opaque, auto) in shared constants for wrapper scripts.","Validate flag values in shell scripts before invoking the CLI.","Omit --background when the default behavior is acceptable."],"tags":["cli","validation","enum-value"],"backgroundTag":"invalid-flag-value","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"}