pbakaus/impeccable · error

comp-spec: pass --grid to get the coordinate grid, then --re

Error message

comp-spec: pass --grid to get the coordinate grid, then --regions <json> (or --auto for band regions)

What it means

After loading the comp image, comp-spec needs a region source: a --regions JSON file, --auto band regions, or --grid to render the coordinate grid first. This guidance error is printed when none of these mode flags is present, exiting 1.

Source

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

    let regions_input: Value = if let Some(rf) = arg(argv, "regions") {
        match std::fs::read_to_string(resolve(io, rf)) {
            Ok(raw) => match serde_json::from_str(&raw) {
                Ok(v) => v,
                Err(e) => {
                    io.err(&format!("comp-spec: cannot read regions {rf}: {e}\n"));
                    return 1;
                }
            },
            Err(e) => {
                io.err(&format!("comp-spec: cannot read regions {rf}: {e}\n"));
                return 1;
            }
        }
    } else if flag(argv, "auto") {
        auto_regions(&comp)
    } else {
        io.err("comp-spec: pass --grid to get the coordinate grid, then --regions <json> (or --auto for band regions)\n");
        return 1;
    };
    let spec = match measure_regions(&comp, &regions_input, comp_path) {
        Ok(s) => s,
        Err(e) => {
            io.err(&format!("comp-spec: {e}\n"));
            return 1;
        }
    };
    let spec_out = resolve(io, &spec_path);
    if let Some(parent) = spec_out.parent() {
        let _ = std::fs::create_dir_all(parent);
    }
    let _ = std::fs::write(&spec_out, util::json_pretty(&spec));
    io.out(&format!("WROTE {spec_path}\n"));
    io.out(&format!("{}\n", print_spec(&spec)));
    let _ = r4f(0.0); // silence unused if optimized away
    0

View on GitHub (pinned to 2bc2879276)

Solutions

1. Add one of the required mode flags: --grid, --regions <json>, or --auto.
2. Check flag spelling — `--region`/`--regions-file` are not recognized; only exact `--regions` counts.
3. If unsure of the workflow, run --grid first and follow the NEXT instructions it prints, then supply regions.json.

Example fix

// before
comp-spec --comp comp.png --region regions.json   // misspelled flag
// after
comp-spec --comp comp.png --regions regions.json

const args = ['comp-spec', '--comp', comp, ...rest];
const hasMode = args.includes('--grid') || args.includes('--auto') || args.includes('--regions');
if (!hasMode) {
  throw new Error('comp-spec needs one of: --grid, --regions <json>, --auto');
}

When it happens

Trigger: Calling `comp-spec --comp <png>` (with --spec or nothing else) without any of --grid, --regions <json>, or --auto — e.g. passing only an unknown/misspelled flag like --region or --grids.

Common situations: Misspelling --regions as --region so the flag parser drops it; intending to re-measure but only passing --spec; composing scripted invocations where the mode flag variable is empty.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• build-phase: start needs --comp <approved comp png> (comp al
• usage: font-match.mjs --measure <text-region-id> | --rank <t
• "init" is not a CLI command. Type /impeccable init in your A
• Unknown command: "{other}" To see a list of supported comma
• usage: build-phase.mjs start --comp <png> [--breakpoint WxH]

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