garrytan/gstack · error · Error

Unknown screenshot flag: ${args[i]}

Error message

Unknown screenshot flag: ${args[i]}

What it means

Thrown by the `screenshot` meta-command parser when an argument begins with `--` but is not one of the recognized flags (`--viewport`, `--base64`, `--selector`, `--clip`). The parser is intentionally strict so typos like `--fullpage` (vs `--viewport`) don't silently fall through and capture the wrong region. The offending token is echoed back in the message.

Source

Thrown at browse/src/meta-commands.ts:463

      const remaining: string[] = [];
      let flagSelector: string | undefined;
      for (let i = 0; i < args.length; i++) {
        if (args[i] === '--viewport') {
          viewportOnly = true;
        } else if (args[i] === '--base64') {
          base64Mode = true;
        } else if (args[i] === '--selector') {
          flagSelector = args[++i];
          if (!flagSelector) throw new Error('Usage: screenshot --selector <css> [path]');
        } else if (args[i] === '--clip') {
          const coords = args[++i];
          if (!coords) throw new Error('Usage: screenshot --clip x,y,w,h [path]');
          const parts = coords.split(',').map(Number);
          if (parts.length !== 4 || parts.some(isNaN))
            throw new Error('Usage: screenshot --clip x,y,width,height — all must be numbers');
          clipRect = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
        } else if (args[i].startsWith('--')) {
          throw new Error(`Unknown screenshot flag: ${args[i]}`);
        } else {
          remaining.push(args[i]);
        }
      }

      // Separate target (selector/@ref) from output path
      for (const arg of remaining) {
        // File paths containing / and ending with an image/pdf extension are never CSS selectors
        const isFilePath = arg.includes('/') && /\.(png|jpe?g|webp|pdf)$/i.test(arg);
        if (isFilePath) {
          outputPath = arg;
        } else if (arg.startsWith('@e') || arg.startsWith('@c') || arg.startsWith('.') || arg.startsWith('#') || arg.includes('[')) {
          targetSelector = arg;
        } else {
          outputPath = arg;
        }
      }

View on GitHub (pinned to 94993f7401)

Solutions

1. Remove the unknown flag; for a full-page capture use `browse screenshot out.png` with NO `--viewport` (full page is the default).
2. For viewport-only capture use `--viewport`; for element capture use `--selector <css>` or a positional `@ref`.
3. If you need a region, use `--clip x,y,width,height` with numeric comma-separated coords.
4. Re-check the flag spelling against the four supported flags: `--viewport`, `--base64`, `--selector`, `--clip`.

Example fix

// before
browse screenshot --fullpage out.png
// after
browse screenshot out.png

const ALLOWED = new Set(['--viewport', '--base64', '--selector', '--clip']);
const flags = args.filter(a => a.startsWith('--'));
const bad = flags.filter(f => !ALLOWED.has(f));
if (bad.length) throw new Error(`Unsupported screenshot flag(s): ${bad.join(', ')}`);

const isScreenshotFlag = (s: string): boolean =>
  s === '--viewport' || s === '--base64' ||
  s === '--selector' || s === '--clip';

try {
  await browse.screenshot(args);
} catch (err) {
  if (/Unknown screenshot flag/.test(err.message)) {
    // strip the bad flag and retry, or surface to the caller
  }
}

When it happens

Trigger: Calling `browse screenshot --fullpage`, `--path /x.png`, `--format png`, or any other `--`-prefixed token the parser does not whitelist (lines 448-463). Only `--viewport`, `--base64`, `--selector <css>`, and `--clip x,y,w,h` are accepted.

Common situations: Misremembering the API (trying `--fullpage` instead of omitting `--viewport`), copy-pasting flags from a different screenshot library (Playwright's `fullPage`, Puppeteer's `--full-page`), or a shell glob/autocomplete inserting an unexpected flag.

Related errors

• Usage: screenshot --selector <css> [path]
• Usage: screenshot --clip x,y,w,h [path]
• pdf: --from-file requires a path
• Unknown pdf flag: ${a}
• pdf: --${flag} requires a value

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/c523124fa2d45a10. Report an issue: GitHub.