{"record":{"id":"c523124fa2d45a10","repo":"garrytan/gstack","slug":"unknown-screenshot-flag-args-i","errorCode":null,"errorMessage":"Unknown screenshot flag: ${args[i]}","messagePattern":"Unknown screenshot flag: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":463,"sourceCode":"      const remaining: string[] = [];\n      let flagSelector: string | undefined;\n      for (let i = 0; i < args.length; i++) {\n        if (args[i] === '--viewport') {\n          viewportOnly = true;\n        } else if (args[i] === '--base64') {\n          base64Mode = true;\n        } else if (args[i] === '--selector') {\n          flagSelector = args[++i];\n          if (!flagSelector) throw new Error('Usage: screenshot --selector <css> [path]');\n        } else if (args[i] === '--clip') {\n          const coords = args[++i];\n          if (!coords) throw new Error('Usage: screenshot --clip x,y,w,h [path]');\n          const parts = coords.split(',').map(Number);\n          if (parts.length !== 4 || parts.some(isNaN))\n            throw new Error('Usage: screenshot --clip x,y,width,height — all must be numbers');\n          clipRect = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };\n        } else if (args[i].startsWith('--')) {\n          throw new Error(`Unknown screenshot flag: ${args[i]}`);\n        } else {\n          remaining.push(args[i]);\n        }\n      }\n\n      // Separate target (selector/@ref) from output path\n      for (const arg of remaining) {\n        // File paths containing / and ending with an image/pdf extension are never CSS selectors\n        const isFilePath = arg.includes('/') && /\\.(png|jpe?g|webp|pdf)$/i.test(arg);\n        if (isFilePath) {\n          outputPath = arg;\n        } else if (arg.startsWith('@e') || arg.startsWith('@c') || arg.startsWith('.') || arg.startsWith('#') || arg.includes('[')) {\n          targetSelector = arg;\n        } else {\n          outputPath = arg;\n        }\n      }\n","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L445-L481","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the unknown flag; for a full-page capture use `browse screenshot out.png` with NO `--viewport` (full page is the default).","For viewport-only capture use `--viewport`; for element capture use `--selector <css>` or a positional `@ref`.","If you need a region, use `--clip x,y,width,height` with numeric comma-separated coords.","Re-check the flag spelling against the four supported flags: `--viewport`, `--base64`, `--selector`, `--clip`."],"exampleFix":"// before\nbrowse screenshot --fullpage out.png\n// after\nbrowse screenshot out.png","handlingStrategy":"validation","validationCode":"const ALLOWED = new Set(['--viewport', '--base64', '--selector', '--clip']);\nconst flags = args.filter(a => a.startsWith('--'));\nconst bad = flags.filter(f => !ALLOWED.has(f));\nif (bad.length) throw new Error(`Unsupported screenshot flag(s): ${bad.join(', ')}`);","typeGuard":"const isScreenshotFlag = (s: string): boolean =>\n  s === '--viewport' || s === '--base64' ||\n  s === '--selector' || s === '--clip';","tryCatchPattern":"try {\n  await browse.screenshot(args);\n} catch (err) {\n  if (/Unknown screenshot flag/.test(err.message)) {\n    // strip the bad flag and retry, or surface to the caller\n  }\n}","preventionTips":["Validate flags against the four supported names before dispatching.","Keep a single constant/Set of allowed flags and reuse it in arg-parsing and help text.","Reject any `--` token not in the set early, before Playwright is involved."],"tags":["screenshot","argument-parsing","cli"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}