{"record":{"id":"8a2fd717730e4823","repo":"jackwener/OpenCLI","slug":"command-fullname-cmd-requires-a-browser-sessio","errorCode":null,"errorMessage":"Command ${fullName(cmd)} requires a browser session but none was provided","messagePattern":"Command (.+?) requires a browser session but none was provided","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":159,"sourceCode":"    const updated = getRegistry().get(fullName(cmd));\n    if (updated?.func) {\n      return runCommandFunc(updated, page, kwargs, debug);\n    }\n    if (updated?.pipeline) return executePipeline(page, updated.pipeline, { args: kwargs, debug });\n  }\n\n  if (cmd.func) return runCommandFunc(cmd, page, kwargs, debug);\n  if (cmd.pipeline) return executePipeline(page, cmd.pipeline, { args: kwargs, debug });\n  throw new CommandExecutionError(\n    `Command ${fullName(cmd)} has no func or pipeline`,\n    'This is likely a bug in the adapter definition. Please report this issue.',\n  );\n}\n\nfunction runCommandFunc(cmd: CliCommand, page: IPage | null, kwargs: CommandArgs, debug: boolean): Promise<unknown> {\n  if (cmd.browser === false) return cmd.func!(kwargs, debug);\n  if (!page) {\n    throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);\n  }\n  return (cmd as BrowserCliCommand).func!(page, kwargs, debug);\n}\n\nfunction resolvePreNav(cmd: CliCommand): string | null {\n  if (cmd.navigateBefore === false) return null;\n  if (typeof cmd.navigateBefore === 'string') return cmd.navigateBefore;\n  // strategy → navigateBefore expansion already happened in normalizeCommand().\n  return null;\n}\n\nfunction urlMatchesDomain(url: string | null | undefined, domain: string | undefined): boolean {\n  if (!url || !domain) return false;\n  try {\n    const hostname = new URL(url).hostname;\n    return hostname === domain || hostname.endsWith(`.${domain}`);\n  } catch {\n    return false;","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L141-L177","documentation":"This CommandExecutionError is thrown by runCommandFunc when a command that requires a browser (i.e. `cmd.browser !== false`) is invoked without a browser session: the `page` argument (IPage) is null. Commands that drive a real browser tab need an established session; non-browser commands opt out with `browser: false`. It means the caller failed to provide or establish the browser context before dispatch.","triggerScenarios":"Calling runCommand (-> runCommandFunc) with page === null for a command whose definition does not set `browser: false`; running a browser command in a non-browser execution mode; the browser session failing to launch or being closed before command dispatch; invoking a browser command through a code path that never attaches a page.","commonSituations":"Running browser-dependent commands where the underlying browser (e.g. via CDP) never connected or crashed earlier in the run; using the library headlessly in CI without a browser available; scripts calling command funcs directly without going through session setup; daemon/extension contexts where the page handle was lost.","solutions":["Ensure a browser session is started and its page is passed to command execution (launch/connect the browser before running browser commands).","If the command genuinely needs no browser, set `browser: false` on its CliCommand definition so runCommandFunc calls func(kwargs, debug) directly.","Check earlier logs for browser launch/CDP connection failures — the null page is usually a downstream symptom of a failed session setup.","Guard invocations: only dispatch commands to the browser path when a live page handle exists; fail earlier with a clear 'no session' message in your own code."],"exampleFix":"// before\nawait runCommand(cmd, null, kwargs, debug); // throws: requires a browser session\n\n// after\nconst page = await browser.newPage();\nawait runCommand(cmd, page, kwargs, debug);","handlingStrategy":"validation","validationCode":"function requireBrowserSession(cmd, page) {\n  if (cmd.browser !== false && !page) {\n    throw new Error(`Command '${cmd.name}' needs a browser session — start one before dispatch`);\n  }\n}\n// call before runCommand: requireBrowserSession(cmd, page);","typeGuard":"function hasLivePage(page) {\n  return page != null && typeof (page as IPage).navigate === 'function';\n}","tryCatchPattern":"try {\n  await runCommand(cmd, page, kwargs, debug);\n} catch (err) {\n  if (err instanceof CommandExecutionError && /requires a browser session/.test(err.message)) {\n    page = await startBrowserSession();\n    await runCommand(cmd, page, kwargs, debug);\n  } else {\n    throw err;\n  }\n}","preventionTips":["Establish and reuse a single browser session for all browser commands in a run.","Mark genuinely non-browser commands with `browser: false` in their definitions.","Check session health (page not closed) between long-running steps.","In CI, verify browser availability before executing browser-dependent commands."],"tags":["browser-session","missing-dependency","cli"],"backgroundTag":"missing-browser-session","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}