pbakaus/impeccable · error

Error: --viewport requires a WxH value, e.g. --viewport 390x

Error message

Error: --viewport requires a WxH value, e.g. --viewport 390x844

What it means

The detect CLI validates the `--viewport` flag against a WxH regex (VIEWPORT_RE) and exits with code 1 if the value doesn't match, printing an example of the expected format. Viewport-scoped detection needs numeric width x height in pixels, so anything else is rejected before scanning starts.

Source

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

                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;
            continue;
        }
        let value: String = if inline {
            args[i]["--viewport=".len()..].to_string()
        } else {
            args.get(i + 1).cloned().unwrap_or_default()
        };
        let Some(m) = VIEWPORT_RE.captures(&value) else {
            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!(

View on GitHub (pinned to 2bc2879276)

Solutions

1. Pass dimensions as WxH with a lowercase x, e.g. `--viewport 390x844` or `--viewport 1280x800`.
2. If the value comes from a variable, ensure it's formatted `"${W}x${H}"` with plain integers and no units.
3. Quote the flag pair in scripts (`--viewport "$V"`) so the value isn't consumed as a separate positional argument.

Example fix

// before
impeccable detect src/ --viewport 390px-844px
// after
impeccable detect src/ --viewport 390x844

const m = /^(\d+)x(\d+)$/.exec(viewport ?? "");
if (!m) throw new Error(`--viewport must be WxH, got: ${viewport}`);

const isViewport = (v) => /^\d+x\d+$/.test(v);

When it happens

Trigger: Running `impeccable detect --viewport` without a value, or with a value that doesn't match `<number>x<number>`, e.g. `--viewport 390`, `--viewport 390X844` (capital X, if the regex is lowercase-only), `--viewport mobile`, or `--viewport=390-844`.

Common situations: Using device names instead of dimensions; pasting viewport strings with units (`390px x 844px`); shell quoting dropping the value; scripts where the WxH string is built with the wrong separator character.

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

• Error: --scope requires a value. Valid scopes: {scopes_valid
• Error: unknown --scope value(s): {}. Valid scopes: {scopes_v
• 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/3f459ff86fc4a1a4. Report an issue: GitHub.