This browser session does not support frame-targeted evaluat

Error message

This browser session does not support frame-targeted evaluation

What it means

The `browser eval` command with a `--frame <index>` option requires `page.evaluateInFrame` to run JavaScript inside a specific iframe. When the backend does not implement frame-targeted evaluation, this capability error is thrown instead of silently evaluating in the wrong context.

Source

Thrown at src/cli.ts:2518

  // ── Extract ──

  addBrowserTabOption(
    browser.command('eval')
      .argument('<js>', 'JavaScript code')
      .option('--frame <index>', 'Cross-origin iframe index from "browser frames"')
      .description('Execute JS in page context, return result'),
  )
    .action(browserAction(async (page, js, opts) => {
      let result: unknown;
      if (opts.frame !== undefined) {
        const frameIndex = Number.parseInt(opts.frame, 10);
        if (!Number.isInteger(frameIndex) || frameIndex < 0) {
          console.error(`Invalid frame index "${opts.frame}". Use a 0-based index from "browser frames".`);
          process.exitCode = EXIT_CODES.USAGE_ERROR;
          return;
        }
        if (!page.evaluateInFrame) {
          throw new Error('This browser session does not support frame-targeted evaluation');
        }
        result = await page.evaluateInFrame(js, frameIndex);
      } else {
        result = await page.evaluate(js);
      }
      if (typeof result === 'string') console.log(result);
      else console.log(JSON.stringify(result, null, 2));
    }));

  // ── Extract (content reading) ──
  //
  // `extract` answers the "read this page" question that `get html` / `get text`
  // can't: denoise → markdown → paragraph-aware chunking. Agents walk long pages
  // by passing back the `next_start_char` cursor instead of juggling selectors.

  addBrowserTabOption(
    browser.command('extract')
      .option('--selector <css>', 'CSS selector scope; defaults to <main>/<article>/<body>')

View on GitHub (pinned to 49907e53dc)

Solutions

Use a backend implementing evaluateInFrame (Playwright/Puppeteer with frame support).
Run the script without `--frame` and target the iframe's contentWindow from the main world via `browser eval` where same-origin.
Get a frame handle differently, e.g. enumerate frames with `browser frames` and use backend-specific frame APIs.

Example fix

// before
browser --backend minimal eval "document.title" --frame 0
// after
browser --backend playwright eval "document.title" --frame 0

Defensive patterns

Strategy: type-guard

Validate before calling

const frameIndex = Number(opts.frame);
const page = await getBrowserPage();
if (Number.isInteger(frameIndex) && frameIndex >= 0 && typeof page.evaluateInFrame !== 'function') {
  throw new Error('Backend lacks frame-targeted evaluation; drop --frame or switch backends');
}

Type guard

function supportsFrameEval(page) {
  return typeof page?.evaluateInFrame === 'function';
}

Try / catch

try {
  await run(['browser', 'eval', js, '--frame', String(i)]);
} catch (err) {
  if (String(err.message).includes('frame-targeted evaluation')) {
    await run(['browser', 'eval', `(()=>{const f=document.querySelectorAll('iframe')[${i}];return f.contentDocument.title})()`]);
  } else throw err;
}

Prevention

Only pass --frame when the backend implements evaluateInFrame.
Check same-origin access to iframes before evaluating inside them.
Use `browser frames` to confirm the index exists.
Fall back to main-world contentWindow access for same-origin frames.

When it happens

Trigger: Running `browser eval <js> --frame 2` (or similar frame option) where `page.evaluateInFrame` is undefined; frame index validity is checked first, so this fires only when the index is a valid non-negative integer but the backend lacks the feature.

Common situations: Minimal/CDP-lite drivers without frame execution support; cross-origin iframes the driver cannot reach; older adapter versions before evaluateInFrame was added.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/8c8913e45dcf9179. Report an issue: GitHub.