jackwener/OpenCLI · error · CommandExecutionError

Chess.com archives payload is missing archives array

Error message

Chess.com archives payload is missing archives array

What it means

After fetching /player/{username}/games/archives via chessApi, the command requires the payload to contain an archives array. If Chess.com returns something else (an error object, null, an HTML page parsed differently), the command throws CommandExecutionError instead of crashing on a missing property.

Source

Thrown at clis/chess/games.js:39

cli({
    site: 'chess',
    name: 'games',
    access: 'read',
    description: 'Chess.com recent games for a player, newest first',
    domain: 'api.chess.com',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'username', type: 'string', required: true, positional: true, help: 'Chess.com username' },
        { name: 'limit', type: 'int', default: 10, help: `Number of recent games (1-${MAX_LIMIT})` },
    ],
    columns: ['date', 'time_class', 'rated', 'my_color', 'my_rating', 'my_result', 'opponent', 'opponent_rating', 'accuracy_white', 'accuracy_black', 'eco', 'opening_name', 'url'],
    func: async (kwargs) => {
        const username = validateUsername(kwargs.username);
        const limit = parseLimit(kwargs.limit);
        const archivesList = await chessApi(`/player/${encodeURIComponent(username)}/games/archives`);
        if (!Array.isArray(archivesList.archives)) {
            throw new CommandExecutionError('Chess.com archives payload is missing archives array');
        }
        const archives = archivesList.archives.slice().reverse();
        if (archives.length === 0) {
            throw new EmptyResultError(`Chess.com has no game archives for ${username}`);
        }
        const rows = [];
        for (let i = 0; i < archives.length && i < MAX_ARCHIVE_FETCHES && rows.length < limit; i++) {
            if (typeof archives[i] !== 'string' || !archives[i].startsWith('https://api.chess.com/pub/player/')) {
                throw new CommandExecutionError('Chess.com archives payload contains an unexpected archive URL');
            }
            const monthly = await chessApi(archives[i]);
            if (!Array.isArray(monthly.games)) {
                throw new CommandExecutionError('Chess.com monthly archive payload is missing games array');
            }
            const games = monthly.games.slice().reverse();
            for (const g of games) {
                rows.push(mapGameRow(g, username));
                if (rows.length >= limit) break;

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Confirm the username exists by fetching https://api.chess.com/pub/player/{username} first
  2. Check Chess.com API status/announcements for schema changes
  3. Capture the raw payload of the archives call to see what was actually returned

Example fix

// before
const list = await chessApi(`/player/${username}/games/archives`);
// after: pre-validate the player exists
const player = await chessApi(`/player/${encodeURIComponent(username)}`);
if (!player || !player.username) throw new Error(`Unknown player ${username}`);
const list = await chessApi(`/player/${encodeURIComponent(username)}/games/archives`);
Defensive patterns

Strategy: type-guard

Validate before calling

// verify the player exists before fetching archives
const player = await fetch(`https://api.chess.com/pub/player/${encodeURIComponent(username)}`).then(r => r.json());
if (!player || !player.username) throw new Error(`Unknown Chess.com user: ${username}`);

Type guard

function hasArchives(p) { return p != null && typeof p === 'object' && Array.isArray(p.archives); }

Try / catch

try {
  await gamesCmd(username);
} catch (e) {
  if (/missing archives array/.test(e.message)) {
    // inspect raw payload / verify username / check for API schema changes
  } else throw e;
}

Prevention

When it happens

Trigger: chessApi receives a 2xx response whose body lacks .archives — e.g. the username doesn't exist but the API returns a non-404 payload, or Chess.com changed the archives response shape.

Common situations: Typo'd or case-sensitive mismatches in usernames; Chess.com API schema changes; proxy/captive portals returning HTML with status 200.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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