jackwener/OpenCLI · error · ArgumentError

<game-url> is required

Error message

<game-url> is required

What it means

An ArgumentError thrown by parseGameUrl when the game-url argument is missing or trims to an empty string. A game URL is required to extract the game kind (live/daily) and numeric game id before any Chess.com game endpoint can be queried.

Source

Thrown at clis/chess/utils.js:32

    return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function isOptionalPlainObject(value) {
    return value === undefined || value === null || isPlainObject(value);
}

export function validateUsername(value) {
    const s = String(value ?? '').trim().toLowerCase();
    if (!s) throw new ArgumentError('<username> is required');
    if (!USERNAME_RE.test(s)) {
        throw new ArgumentError(`Invalid Chess.com username "${value}"`, 'Usernames are 3-25 chars: a-z, 0-9, hyphen, underscore.');
    }
    return s;
}

export function parseGameUrl(value) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError('<game-url> is required');
    const m = s.match(GAME_URL_RE);
    if (!m) {
        throw new ArgumentError(
            `Invalid Chess.com game URL: "${value}"`,
            'Expected https://www.chess.com/game/live/<id> or https://www.chess.com/game/daily/<id>.',
        );
    }
    return { kind: m[1].toLowerCase(), id: m[2] };
}

export async function chessApi(path, fetchImpl = fetch) {
    const url = path.startsWith('http') ? path : `${API_BASE}${path}`;
    let resp;
    try {
        resp = await fetchImpl(url, { headers: { 'User-Agent': UA, accept: 'application/json' } });
    } catch (error) {
        throw new CommandExecutionError(`Failed to fetch Chess.com API ${url}: ${error?.message || error}`);
    }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Provide the game URL, e.g. https://www.chess.com/game/live/123456789.
2. Verify the shell variable or config value feeding the flag is set and non-empty.
3. Add a required-argument check at the CLI layer for clearer usage output.

Example fix

// before
await chessGame({ gameUrl: process.env.LAST_GAME }); // unset -> throws
// after
if (!process.env.LAST_GAME) throw new Error('LAST_GAME is required');
await chessGame({ gameUrl: process.env.LAST_GAME });

function requireGameUrl(value) {
  const s = String(value ?? '').trim();
  if (!s) throw new Error('game URL is required before calling the chess API');
  return s;
}

function hasGameUrl(args) {
  return typeof args.gameUrl === 'string' && args.gameUrl.trim().length > 0;
}

try {
  const game = await chessGame({ gameUrl });
} catch (e) {
  if (e.name === 'ArgumentError' && /game-url is required/i.test(e.message)) {
    console.error('Usage: opencli chess game --game-url https://www.chess.com/game/live/<id>');
  } else throw e;
}

When it happens

Trigger: Invoking a game command without the --game-url argument, or passing an empty/whitespace-only value.

Common situations: Forgetting the flag entirely; a shell variable holding the URL is unset so the flag expands to an empty string (--game-url "$GAME_URL" with GAME_URL='').

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

• symbol is required
• <username> is required
• Either --product-id or --url is required
• --city is required (numeric city ID from `ctrip search` or `
• --${name} is required (e.g. 北京 / 上海)

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