jackwener/OpenCLI · error · CommandExecutionError

Chess.com callback returned no game payload

Error message

Chess.com callback returned no game payload

What it means

summarizeGame validates the raw payload returned by the Chess.com callback before building a row; it throws CommandExecutionError when the payload is not a plain object or lacks a plain-object `game` field, since no summary can be derived without it.

Source

Thrown at clis/chess/game.js:22

 * PGN headers + move data plus per-player metadata.
 */
import { cli, Strategy } from '@jackwener/opencli/registry';
import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
import { UA, formatDate, isPlainObject, parseGameUrl } from './utils.js';

const CALLBACK_BASE = 'https://www.chess.com/callback';

function stringOrEmpty(value) {
    return typeof value === 'string' ? value : '';
}

function scalarOrEmpty(value) {
    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? value : '';
}

export function summarizeGame({ kind, id, payload }) {
    if (!isPlainObject(payload) || !isPlainObject(payload.game)) {
        throw new CommandExecutionError('Chess.com callback returned no game payload');
    }
    const g = payload.game;
    if (g.pgnHeaders !== undefined && !isPlainObject(g.pgnHeaders)) {
        throw new CommandExecutionError('Chess.com callback returned malformed PGN headers');
    }
    if (payload.players !== undefined && !isPlainObject(payload.players)) {
        throw new CommandExecutionError('Chess.com callback returned malformed player metadata');
    }
    const players = payload.players || {};
    const byColor = {};
    for (const slot of ['top', 'bottom']) {
        const p = players[slot];
        if (p !== undefined && !isPlainObject(p)) {
            throw new CommandExecutionError('Chess.com callback returned malformed player metadata');
        }
        if (p?.color) byColor[p.color] = p;
    }
    const white = byColor.white || {};

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Log/inspect the raw callback response to see what was actually returned.
  2. Retry the fetch — a transient bad response can masquerade as a schema problem.
  3. Check whether Chess.com changed the callback response shape and update the CLI's parsing accordingly.
  4. Validate the response is JSON before calling summarizeGame (check content-type and try/catch the parse).

Example fix

// before
const row = summarizeGame({ kind, id, payload }); // payload may be junk
// after
if (!isPlainObject(payload) || !isPlainObject(payload.game)) {
  throw new CommandExecutionError('Chess.com callback returned no game payload');
}
const row = summarizeGame({ kind, id, payload });
Defensive patterns

Strategy: type-guard

Validate before calling

const body = await resp.text();
let payload; try { payload = JSON.parse(body); } catch { throw new Error('Callback response is not JSON'); }

Type guard

const isPlainObject = (v) => Object.prototype.toString.call(v) === '[object Object]';
const hasGamePayload = (p) => isPlainObject(p) && isPlainObject(p.game);

Try / catch

try {
  const row = summarizeGame({ kind, id, payload });
} catch (err) {
  if (String(err.message).includes('no game payload')) {
    console.error('Unexpected callback response; dumping raw body for inspection');
  } else throw err;
}

Prevention

When it happens

Trigger: The callback response body is not JSON-shaped as expected (HTML error page parsed weirdly, empty body, API schema change) so payload or payload.game is missing/not an object when summarizeGame runs.

Common situations: Chess.com changed their callback response schema; the fetch succeeded but returned an error page; proxies/CDNs returning HTML instead of JSON; version drift between the CLI and the endpoint.

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/ada9c111b793e781. Report an issue: GitHub.