jackwener/OpenCLI · error · CommandExecutionError

${label} returned an unexpected payload shape; expected an a

Error message

${label} returned an unexpected payload shape; expected an array.

What it means

A CommandExecutionError thrown by requireArray (clis/dongchedi/utils.js:117), a schema guard called by parseKoubei, parseModels, and the sameLevelAverage/data parsing paths. It fires when a pageProps field expected to be a JSON array arrives as null, an object, or a scalar — typically because the upstream block is missing or its shape changed.

Source

Thrown at clis/dongchedi/utils.js:117

    if (isFallbackShell(pp)) {
        throw new CommandExecutionError(
            `dongchedi ${contextHint}`,
            'Dongchedi served its empty fallback shell — the id may not exist or the URL form changed.',
        );
    }
    return pp;
}

export function assertPlainObject(value, label) {
    if (!value || typeof value !== 'object' || Array.isArray(value)) {
        throw new CommandExecutionError(`${label} returned an unexpected payload shape; expected an object.`);
    }
    return value;
}

export function requireArray(value, label) {
    if (!Array.isArray(value)) {
        throw new CommandExecutionError(`${label} returned an unexpected payload shape; expected an array.`);
    }
    return value;
}

export function requireStableId(value, label) {
    const id = String(value ?? '').trim();
    if (!/^\d+$/.test(id) || id === '0') {
        throw new CommandExecutionError(`${label} did not include a stable numeric id.`);
    }
    return id;
}

export function requireText(value, label) {
    const text = clean(value);
    if (!text) {
        throw new CommandExecutionError(`${label} did not include a stable text value.`);
    }
    return text;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Inspect the live pageProps key being passed to requireArray and confirm its actual type; update the parser key or shape handling if the site changed.
2. For items that legitimately lack the list (no reviews/scores), handle the empty case before calling the parser.
3. Catch CommandExecutionError in the command and return an empty table with a notice instead of crashing.
4. Fix test fixtures to mirror the real array-typed SSR payload.

Example fix

// before
const list = requireArray(pp.reviewList, 'koubei reviews'); // throws when absent
// after
const list = Array.isArray(pp.reviewList) ? requireArray(pp.reviewList, 'koubei reviews') : [];

function isArray(v) {
  return Array.isArray(v);
}

if (!Array.isArray(pp.reviewList)) {
  return []; // treat absent list (e.g. no reviews) as empty, not an error
}
const list = requireArray(pp.reviewList, 'koubei reviews');

When it happens

Trigger: Running dongchedi koubei, models, or score commands when the reviews/models/score-list block in pageProps is null (no data for the item), became an object after a site schema change, or the wrong pageProps key is being read.

Common situations: Querying cars with zero reviews/owner scores (the list block is genuinely absent); a Dongchedi redeploy restructuring a list field; stale test fixtures passing objects where the site sends arrays.

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

• ${label} returned an unexpected payload shape; expected an o
• ${label} did not include a stable numeric id.
• ${label} did not include a stable text value.
• dongchedi specs ${seriesId}: No spec overview found for this
• Sales Navigator lead search API returned malformed lead row

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