jackwener/OpenCLI · error · CommandExecutionError

Browser session required for chess analyze

Error message

Browser session required for chess analyze

What it means

The chess analyze command operates on a live browser page (it navigates to Chess.com's analysis board), so it throws CommandExecutionError when invoked without an active browser session (page is null/falsy). This guards against running the command before a session is established.

Source

Thrown at clis/chess/analyze.js:24

import { cli, Strategy } from '@jackwener/opencli/registry';
import { CommandExecutionError } from '@jackwener/opencli/errors';
import { parseGameUrl } from './utils.js';

cli({
    site: 'chess',
    name: 'analyze',
    access: 'read',
    description: 'Open a Chess.com game in the browser analysis board',
    domain: 'www.chess.com',
    strategy: Strategy.UI,
    browser: true,
    navigateBefore: false,
    args: [
        { name: 'game-url', type: 'string', required: true, positional: true, help: 'Full game URL, e.g. https://www.chess.com/game/live/168842570216' },
    ],
    columns: ['kind', 'game_id', 'analysis_url'],
    func: async (page, kwargs) => {
        if (!page) throw new CommandExecutionError('Browser session required for chess analyze');
        const { kind, id } = parseGameUrl(kwargs['game-url']);
        const analysisUrl = `https://www.chess.com/analysis/game/${kind}/${id}`;
        try {
            await page.goto(analysisUrl);
            await page.wait(2);
        } catch (error) {
            throw new CommandExecutionError(`Failed to open Chess.com analysis board: ${error?.message || error}`);
        }
        return [{ kind, game_id: id, analysis_url: analysisUrl }];
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Start/ensure a browser session before running chess analyze (the command that yields the `page`).
2. Reopen the browser session if it was closed or crashed, then re-run the command.
3. In automation, assert the page handle exists before invoking the command and fail early with a clearer message.

Example fix

// before
await chessAnalyze({ gameUrl }); // page not open
// after
const page = await openBrowserSession();
await chessAnalyze({ page, gameUrl });

if (!page) throw new Error('Open a browser session before running chess analyze');

function hasPage(session) { return Boolean(session && typeof session.goto === 'function'); }

try {
  await chessAnalyze({ page, gameUrl });
} catch (err) {
  if (String(err.message).includes('Browser session required')) {
    page = await openBrowserSession();
    await chessAnalyze({ page, gameUrl });
  } else throw err;
}

When it happens

Trigger: Running `chess analyze <game-url>` in an environment where no browser session exists — e.g. no prior session/login command opened a page, the session was closed, or the command was invoked headlessly without a page handle.

Common situations: Running the CLI fresh without starting the browser session; the browser crashed or was closed between commands; automation pipelines calling chess analyze out of order before session setup.

Related errors

• 12306 whoami failed: ${probe.detail}
• linux.do requires an active signed-in browser session
• Please verify your linux.do session is still valid
• Browser session required for zhihu answer
• Command ${fullName(cmd)} requires a browser session but none

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