garrytan/gstack · error · Error

Usage: frame <selector|@ref|--name name|--url pattern|main>

Error message

Usage: frame <selector|@ref|--name name|--url pattern|main>

What it means

The `frame` meta-command requires a target argument selecting which frame to switch to (line 1003): a CSS selector, an `@ref`, `--name <name>`, `--url <pattern>`, or the literal `main`. With no target the command cannot decide which frame to enter, so it throws this usage error.

Source

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

        // checks, or forge tab ownership for cross-agent authorization bypass.
        await bm.restoreState({
          cookies: validatedCookies,
          pages: data.pages.map((p: any) => ({
            url: typeof p.url === 'string' ? p.url : '',
            isActive: Boolean(p.isActive),
            storage: null,
          })),
        });
        return `State loaded: ${data.cookies.length} cookies, ${data.pages.length} pages`;
      }

      throw new Error('Usage: state save|load <name>');
    }

    // ─── Frame ───────────────────────────────────────
    case 'frame': {
      const target = args[0];
      if (!target) throw new Error('Usage: frame <selector|@ref|--name name|--url pattern|main>');

      if (target === 'main') {
        bm.setFrame(null);
        bm.clearRefs();
        return 'Switched to main frame';
      }

      const page = bm.getPage();
      let frame: Frame | null = null;

      if (target === '--name') {
        if (!args[1]) throw new Error('Usage: frame --name <name>');
        frame = page.frame({ name: args[1] });
      } else if (target === '--url') {
        if (!args[1]) throw new Error('Usage: frame --url <pattern>');
        frame = page.frame({ url: new RegExp(escapeRegExp(args[1])) });
      } else {
        // CSS selector or @ref for the iframe element

View on GitHub (pinned to 94993f7401)

Solutions

1. Switch to main: `browse frame main`.
2. By name: `browse frame --name <frameName>`.
3. By URL pattern: `browse frame --url 'example\.com/embed'`.
4. By element: `browse frame iframe#widget` or `browse frame @e5`.

Example fix

// before
browse frame
// after
browse frame main

if (!args[0]) {
  throw new Error('frame requires a target: <selector|@ref|--name n|--url pattern|main>');
}

const isFrameTarget = (s: string): boolean =>
  s === 'main' || s === '--name' || s === '--url' ||
  /^(?:@e|@c|\.|#|\[)/.test(s);

When it happens

Trigger: `browse frame` with no arguments.

Common situations: Forgetting to pass the iframe selector; an agent constructing the call lazily; expecting the command to auto-pick the only frame.

Related errors

• Usage: frame --name <name>
• Usage: frame --url <pattern>
• Usage: echo '[["goto","url"],["text"]]' | browse chain or
• Usage: browse diff <url1> <url2>
• Usage: state save|load <name>

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