This browser session does not support explicit tab targeting

Error message

This browser session does not support explicit tab targeting

What it means

After resolving which tab should receive the command, the CLI calls page.setActivePage to switch focus. If the connected session's page object does not implement setActivePage, the session simply cannot support explicit tab targeting, and the library throws rather than silently running against the wrong tab.

Source

Thrown at src/cli.ts:633

  const bridge = new BrowserBridge();
  // Internal GC timeout for browser sessions. Not the per-command runtime timeout.
  const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
  const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
  const page = await bridge.connect({
    timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
    session,
    surface: 'browser',
    ...profileRouteParams(profileSelection),
    ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
    windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),
  });
  const targetScope = getBrowserScope(session, profileSelection?.contextId);
  const resolvedTargetPage = targetPage
    ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })
    : await resolveStoredBrowserTarget(page, targetScope);
  if (resolvedTargetPage) {
    if (!page.setActivePage) {
      throw new Error('This browser session does not support explicit tab targeting');
    }
    page.setActivePage(resolvedTargetPage);
  }
  return page;
}

function getBrowserWindowMode(command: Command | undefined, defaultMode: BrowserWindowMode): BrowserWindowMode {
  const optionRaw = getCommandOption(command, 'window');
  if (optionRaw !== undefined && optionRaw !== '') {
    if (optionRaw === 'foreground' || optionRaw === 'background') return optionRaw;
    throw new Error(`--window must be one of: foreground, background. Received: "${String(optionRaw)}"`);
  }
  const envRaw = process.env.OPENCLI_WINDOW;
  if (envRaw !== undefined && envRaw !== '') {
    if (envRaw === 'foreground' || envRaw === 'background') return envRaw;
    throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"`);
  }
  return defaultMode;

View on GitHub (pinned to 49907e53dc)

Solutions

Upgrade the browser bridge/driver to a version that supports setActivePage (multi-tab targeting).
Drop the explicit target/stored target and run against the session's default active page.
Verify which browser backend the session uses and switch to one supporting tab targeting.
For tests, use a full driver mock that implements setActivePage instead of a minimal page stub.

Example fix

// before
const page = await connect(legacyBridge); // no setActivePage
await run(page, { targetPage: 'tab-2' });
// after
const page = await connect(bridgeWithMultiTab);
await run(page, { targetPage: 'tab-2' });

Defensive patterns

Strategy: fallback

Validate before calling

function supportsTabTargeting(page) {
  return typeof (page as { setActivePage?: unknown }).setActivePage === 'function';
}
if (!supportsTabTargeting(page)) console.warn('session lacks tab targeting; using default page');

Type guard

function supportsTabTargeting(page: Page): page is Page & { setActivePage: (p: unknown) => void } {
  return typeof (page as { setActivePage?: unknown }).setActivePage === 'function';
}

Try / catch

try {
  return await connectBrowser(session, { targetPage });
} catch (err) {
  if (err instanceof Error && err.message.includes('does not support explicit tab targeting')) {
    return connectBrowser(session, {}); // default page
  }
  throw err;
}

Prevention

Verify bridge/driver version supports multi-tab before relying on targetPage.
Guard with a capability check (typeof page.setActivePage === 'function') before targeting.
Use a full-featured driver in test stubs if commands may need tab switching.
Prefer the default active page when multi-tab support is uncertain.

When it happens

Trigger: A targetPage was given (or a stored target resolved) and resolvedTargetPage is truthy, but the returned session page lacks a setActivePage method — e.g. a driver/bridge implementation that only exposes a single active page.

Common situations: Pointing opencli at an older or alternative browser bridge that predates multi-tab support; a custom/driver stub used in tests; switching between browser backends where the new backend lacks the API.

Related errors

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