garrytan/gstack · error · Error

Usage: screenshot --clip x,y,w,h [path]

Error message

Usage: screenshot --clip x,y,w,h [path]

What it means

Thrown by the screenshot command when --clip is the last token in argv — the (++i) increment reads undefined. The --clip flag requires a coordinate string in 'x,y,w,h' format to define the crop rectangle.

Source

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

      let outputPath = `${TEMP_DIR}/browse-screenshot.png`;
      let clipRect: { x: number; y: number; width: number; height: number } | undefined;
      let targetSelector: string | undefined;
      let viewportOnly = false;
      let base64Mode = false;

      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('[')) {

View on GitHub (pinned to 94993f7401)

Solutions

  1. Provide the coordinate string immediately after --clip, e.g., 'screenshot --clip 0,0,800,600 out.png'
  2. If building the command programmatically, ensure the clip coordinates variable is non-empty

Example fix

# before
$B screenshot --clip

# after
$B screenshot --clip 0,0,800,600 out.png
Defensive patterns

Strategy: validation

Validate before calling

const idx = args.indexOf('--clip');
if (idx !== -1 && (idx === args.length - 1 || !args[idx + 1])) {
  throw new Error('--clip requires a coordinate string');
}

Prevention

When it happens

Trigger: Passing '--clip' as the final argument with no subsequent value, e.g., 'screenshot --clip'.

Common situations: User forgets the coordinate string, or a script omits the value.

Related errors

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