pbakaus/impeccable · error

Error: --scope requires a value. Valid scopes: {scopes_valid

Error message

Error: --scope requires a value. Valid scopes: {scopes_valid}

What it means

The detect CLI exits with code 1 when `--scope` is given without any usable value: after parsing the flag's value (inline `--scope=...` or the next argument), splitting on commas, and trimming, the resulting list is empty. The message lists the valid scope names so the caller can correct the flag.

Source

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

        if args[i] != "--scope" && !inline {
            i += 1;
            continue;
        }
        let value: Option<String> = if inline {
            Some(args[i]["--scope=".len()..].to_string())
        } else {
            args.get(i + 1).cloned()
        };
        let parsed: Vec<String> = match value {
            Some(v) if !v.starts_with("--") => v
                .split(',')
                .map(|s| impeccable_core::js::trim(s).to_string())
                .filter(|s| !s.is_empty())
                .collect(),
            _ => vec![],
        };
        if parsed.is_empty() {
            io.err(&format!(
                "Error: --scope requires a value. Valid scopes: {scopes_valid}\n"
            ));
            return Err(Exit(1));
        }
        scopes.extend(parsed);
        let n = if inline { 1 } else { 2 };
        for _ in 0..n {
            if i < args.len() {
                args.remove(i);
            }
        }
    }
    let mut viewport: Option<(u32, u32)> = None;
    let mut i = 0;
    while i < args.len() {
        let inline = args[i].starts_with("--viewport=");
        if args[i] != "--viewport" && !inline {
            i += 1;

View on GitHub (pinned to 2bc2879276)

Solutions

1. Pass at least one valid scope value, e.g. `impeccable detect src/ --scope layout` (check the Valid scopes list printed in the message for exact names).
2. Use the comma-separated inline form for multiple scopes: `--scope=layout,spacing`.
3. Fix shell quoting/variable expansion so the value is not empty (e.g. `--scope "${SCOPES:-all}"` or guard the variable).

Example fix

// before
impeccable detect src/ --scope "$MY_SCOPES"   # MY_SCOPES empty
// after
impeccable detect src/ --scope layout,spacing

const scopeFlagIdx = argv.indexOf("--scope");
const val = scopeFlagIdx >= 0 ? argv[scopeFlagIdx + 1] : (argv.find(a => a.startsWith("--scope=")) || "=").slice(8);
if (!val || !val.split(",").some(s => s.trim())) {
  throw new Error("--scope requires a non-empty comma-separated value");
}

When it happens

Trigger: Running `impeccable detect --scope` with no following argument, `--scope=` with an empty value, or `--scope ,,` / whitespace-only values that trim to nothing.

Common situations: Script variables interpolating to empty (`--scope $SCOPES` with SCOPES unset); copied command lines where the scope value was stripped by a quoting bug; typos like `--scope: layout` that the parser doesn't recognize as inline form.

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

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

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