pbakaus/impeccable · error

Error: unknown --scope value(s): {}. Valid scopes: {scopes_v

Error message

Error: unknown --scope value(s): {}. Valid scopes: {scopes_valid}

What it means

After collecting `--scope` values, the detect CLI filters them against the set of valid scope names and exits with code 1 if any value is unrecognized. The message echoes the unknown value(s) and the list of valid scopes, so the developer can see exactly which token was wrong.

Source

Thrown at crates/detect/src/cli.rs:495

            io.err("Error: --viewport requires a WxH value, e.g. --viewport 390x844\n");
            return Err(Exit(1));
        };
        viewport = Some((m[1].parse().unwrap_or(0), m[2].parse().unwrap_or(0)));
        let n = if inline { 1 } else { 2 };
        for _ in 0..n {
            if i < args.len() {
                args.remove(i);
            }
        }
    }
    let valid = rule_scopes();
    let unknown: Vec<&String> = scopes
        .iter()
        .filter(|s| !valid.contains(&s.as_str()))
        .collect();
    if !unknown.is_empty() {
        let list: Vec<&str> = unknown.iter().map(|s| s.as_str()).collect();
        io.err(&format!(
            "Error: unknown --scope value(s): {}. Valid scopes: {scopes_valid}\n",
            list.join(", ")
        ));
        return Err(Exit(1));
    }
    let design_system_enabled = config_enabled
        && !has(&args, "--no-design-system")
        && detection_config.design_system_not_disabled();
    let inline_ignores_enabled = config_enabled && !has(&args, "--no-inline-ignores");
    let base = ScanOptions {
        inline_ignores: inline_ignores_enabled,
        design_system: None,
        viewport,
        profile: None,
        // The `impeccable` binary installs no rule pack; a library caller that
        // does sets this before handing the options to an engine.
        rule_pack: None,
    };

View on GitHub (pinned to 2bc2879276)

Solutions

1. Read the `Valid scopes:` list from the message and replace the unknown values with exact matches (case-sensitive), e.g. `--scope layout,spacing`.
2. Run `impeccable detect --help` to see the current scope names.
3. Update any scripts/configs that hard-code scope lists after upgrading the CLI.

Example fix

// before
impeccable detect src/ --scope layouts,touch
// after
impeccable detect src/ --scope layout,touch-targets

const VALID_SCOPES = new Set(["layout", "spacing"]); // keep in sync with CLI --help
const scopes = (scopeArg ?? "").split(",").map(s => s.trim()).filter(Boolean);
const unknown = scopes.filter(s => !VALID_SCOPES.has(s));
if (unknown.length) throw new Error(`unknown scopes: ${unknown.join(", ")}`);

const r = spawnSync("impeccable", ["detect", ...args]);
if (r.status !== 0 && /unknown --scope value/.test(r.stderr.toString())) {
  console.error("Scope names out of date — refresh from `impeccable detect --help`.");
}

When it happens

Trigger: Running e.g. `impeccable detect src/ --scope layouts` or `--scope typography,colour` where one or more comma-separated values are not in the valid scopes list.

Common situations: Typos or wrong plurality of scope names; guessing scope names from other tools' vocabularies; config files or scripts with hard-coded scope lists that drifted from the current CLI's supported set.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Error: --scope requires a value. Valid scopes: {scopes_valid
• build-phase: finish --disposition ship|fix|rebuild|recapture
• Error: --viewport requires a WxH value, e.g. --viewport 390x
• invalid session id: ${id}
• comp-spec: cannot read regions {rf}: {e}

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