jackwener/OpenCLI · error

Browser page is missing a session

Error message

Browser page is missing a session

What it means

A browser page object must carry a `session` string property identifying which browser session it belongs to. getPageSession narrows and trims it, throwing when the property is missing, not a string, or blank. This is an internal invariant: pages returned by the browser layer are expected to always be session-tagged.

Source

Thrown at src/cli.ts:691

function getBrowserSession(command?: Command): string {
  // The CLI surface is `opencli browser <session> <subcommand>`. main.ts rewrites
  // argv to insert `--session <name>` before commander parses it; this helper
  // reads back the rewritten flag.
  const raw = getCommandOption(command, 'session');
  if (typeof raw === 'string' && raw.trim()) return raw.trim();
  throw new Error('<session> is a required positional argument: opencli browser <session> <command>');
}

function getBrowserProfileSelection(command?: Command): ProfileSelection | undefined {
  const raw = getCommandOption(command, 'profile');
  return resolveProfileSelection(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
}

function getPageSession(page: import('./types.js').IPage): string {
  const session = (page as unknown as { session?: unknown }).session;
  if (typeof session === 'string' && session.trim()) return session.trim();
  throw new Error('Browser page is missing a session');
}

function getPageScope(page: import('./types.js').IPage): string {
  // Scope is keyed by the SELECTED profile (explicit or preferred), matching
  // getBrowserPage's targetScope — reading only the explicit contextId would
  // save and look up the remembered tab under different keys whenever the
  // profile came from the config default.
  const { contextId, preferredContextId } = page as unknown as { contextId?: unknown; preferredContextId?: unknown };
  const selected = typeof contextId === 'string' && contextId.trim()
    ? contextId.trim()
    : (typeof preferredContextId === 'string' && preferredContextId.trim() ? preferredContextId.trim() : undefined);
  return getBrowserScope(getPageSession(page), selected);
}

type SnapshotSource = 'dom' | 'ax';

function snapshotMetricText(snapshot: unknown): string {
  return typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);

View on GitHub (pinned to 49907e53dc)

Solutions

1. Ensure the page factory sets `session` (non-empty string) on every IPage it returns
2. Update custom page/mock implementations to include the session property
3. Check plugin/adapter versions — an older page object may predate session tagging
4. If invoking browser commands, use pages obtained from the library's own open/session APIs rather than hand-built objects

Example fix

// before
const page = { url: () => 'about:blank' } as IPage;
// after
const page = { url: () => 'about:blank', session: 'my-session' } as IPage;

function assertPageHasSession(page: IPage): string {
  const s = (page as { session?: unknown }).session;
  if (typeof s !== 'string' || !s.trim()) throw new Error('page must carry a non-empty session string');
  return s.trim();
}

function hasSession(page: IPage): page is IPage & { session: string } {
  const s = (page as { session?: unknown }).session;
  return typeof s === 'string' && s.trim().length > 0;
}

try {
  const session = getPageSession(page);
} catch (e) {
  if ((e as Error).message === 'Browser page is missing a session') {
    throw new Error('Page adapter is outdated: it must set page.session');
  }
  throw e;
}

When it happens

Trigger: A page implementation (custom or mock IPage) does not set `session`; or a session property is an empty/whitespace string; or a page from an older plugin version predates session tagging.

Common situations: Custom page adapters not updated after the session-scoping feature; test doubles/stubs for IPage that omit the session field; deserialized page objects losing the property.

Related errors

• ${label} failed: ${error?.message ?? error}
• ${config.site} login
• Failed to extract AIbase daily news: ${getErrorMessage(error
• antigravity cookies: document.cookie is empty.
• antigravity idb-list: No IndexedDB databases.

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