jackwener/OpenCLI · error · CommandFailure

session_required

session_required

Error message

Browser session is required.

What it means

getSessionName validates that a browser session name was supplied to extension/background command routing; an empty, whitespace-only, or missing session string throws CommandFailure with code 'session_required'. The extension multiplexes multiple named browser sessions, so every lease/container operation must name its target session.

Source

Thrown at extension/src/background.ts:400

  lifecycle?: LeaseLifecycle;
};
const sessionOverrides = new Map<string, SessionOverrides>();

function setSessionOverride(key: string, patch: SessionOverrides): void {
  sessionOverrides.set(key, { ...sessionOverrides.get(key), ...patch });
}

/** Commands currently executing per lease — idle release is deferred while > 0. */
const activeCommandCounts = new Map<string, number>();
const LEASE_KEY_SEPARATOR = '\u0000';

function getLeaseKey(session: string, surface: BrowserSurface): string {
  return `${surface}${LEASE_KEY_SEPARATOR}${encodeURIComponent(session)}`;
}

function getSessionName(session?: string): string {
  const raw = session?.trim();
  if (!raw) throw new CommandFailure(
    'session_required',
    'Browser session is required.',
    'Pass a browser session name, e.g. opencli browser <session> <command>.',
  );
  return raw;
}

function getCommandSurface(cmd: Pick<Command, 'surface' | 'session'>): BrowserSurface {
  return cmd.surface === 'adapter' ? 'adapter' : 'browser';
}

function getSurfaceFromKey(key: string): BrowserSurface {
  return key.split(LEASE_KEY_SEPARATOR, 1)[0] === 'adapter' ? 'adapter' : 'browser';
}

function getSessionFromKey(key: string): string {
  const idx = key.indexOf(LEASE_KEY_SEPARATOR);
  if (idx === -1) return key;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Include a session name in the command: opencli browser <session> <command>
2. Check your script for an empty SESSION variable being interpolated
3. List existing sessions to pick a valid name before running the command

Example fix

// before
await runBrowserCommand({ args: ['status'] });
// after
const session = process.env.OPENCLI_SESSION;
if (!session?.trim()) throw new Error('OPENCLI_SESSION is not set');
await runBrowserCommand({ args: [session, 'status'] });

const session = args[0];
if (typeof session !== 'string' || !session.trim()) {
  throw new Error('Usage: opencli browser <session> <command>');
}

const hasSession = (s) => typeof s === 'string' && s.trim().length > 0;

try {
  await run(cmdArgs);
} catch (e) {
  if (e.code === 'session_required') {
    console.error('A browser session name is required: opencli browser <session> <command>');
  } else throw e;
}

When it happens

Trigger: Invoking an extension browser command via 'opencli browser <session> <command>' with the session token omitted or only whitespace, so the router calls getSessionName(undefined/'' /' ').

Common situations: Typing 'opencli browser status' instead of 'opencli browser mysession status'; scripts that interpolated an empty session variable; callers migrating from single-session versions of the CLI.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• bbc topic "${args.topic}" is not supported
• bbc ${label} must be a positive integer
• bbc ${label} must be <= ${maxValue}
• ARGUMENT
• ${label} must be a positive integer

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