{"record":{"id":"b2b3a288431bcf4b","repo":"jackwener/OpenCLI","slug":"this-browser-session-does-not-support-explicit-tab","errorCode":null,"errorMessage":"This browser session does not support explicit tab targeting","messagePattern":"This browser session does not support explicit tab targeting","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli.ts","lineNumber":633,"sourceCode":"  const bridge = new BrowserBridge();\n  // Internal GC timeout for browser sessions. Not the per-command runtime timeout.\n  const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;\n  const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;\n  const page = await bridge.connect({\n    timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,\n    session,\n    surface: 'browser',\n    ...profileRouteParams(profileSelection),\n    ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),\n    windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),\n  });\n  const targetScope = getBrowserScope(session, profileSelection?.contextId);\n  const resolvedTargetPage = targetPage\n    ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })\n    : await resolveStoredBrowserTarget(page, targetScope);\n  if (resolvedTargetPage) {\n    if (!page.setActivePage) {\n      throw new Error('This browser session does not support explicit tab targeting');\n    }\n    page.setActivePage(resolvedTargetPage);\n  }\n  return page;\n}\n\nfunction getBrowserWindowMode(command: Command | undefined, defaultMode: BrowserWindowMode): BrowserWindowMode {\n  const optionRaw = getCommandOption(command, 'window');\n  if (optionRaw !== undefined && optionRaw !== '') {\n    if (optionRaw === 'foreground' || optionRaw === 'background') return optionRaw;\n    throw new Error(`--window must be one of: foreground, background. Received: \"${String(optionRaw)}\"`);\n  }\n  const envRaw = process.env.OPENCLI_WINDOW;\n  if (envRaw !== undefined && envRaw !== '') {\n    if (envRaw === 'foreground' || envRaw === 'background') return envRaw;\n    throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: \"${envRaw}\"`);\n  }\n  return defaultMode;","sourceCodeStart":615,"sourceCodeEnd":651,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/cli.ts#L615-L651","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst page = await connect(legacyBridge); // no setActivePage\nawait run(page, { targetPage: 'tab-2' });\n// after\nconst page = await connect(bridgeWithMultiTab);\nawait run(page, { targetPage: 'tab-2' });","handlingStrategy":"fallback","validationCode":"function supportsTabTargeting(page) {\n  return typeof (page as { setActivePage?: unknown }).setActivePage === 'function';\n}\nif (!supportsTabTargeting(page)) console.warn('session lacks tab targeting; using default page');","typeGuard":"function supportsTabTargeting(page: Page): page is Page & { setActivePage: (p: unknown) => void } {\n  return typeof (page as { setActivePage?: unknown }).setActivePage === 'function';\n}","tryCatchPattern":"try {\n  return await connectBrowser(session, { targetPage });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('does not support explicit tab targeting')) {\n    return connectBrowser(session, {}); // default page\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["browser","capability-missing","tab-targeting","driver"],"backgroundTag":"unsupported-capability","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}