jackwener/OpenCLI · error · CommandExecutionError

Boss friend list response did not include zpData.friendList

Error message

Boss friend list response did not include zpData.friendList

What it means

fetchFriendList expects a successful BOSS friend-list response to carry data.zpData.friendList as an array. When allowNonZero is false (or code was 0) but zpData.friendList is missing or not an array, the library throws CommandExecutionError — the API replied 'successfully' but with an unexpected shape, so its contract changed or the payload was truncated.

Source

Thrown at clis/boss/utils.js:162

    // Auto-check auth unless caller opts out
    if (!opts.allowNonZero && data.code !== 0) {
        assertOk(data);
    }
    return data;
}
// ── Convenience helpers ─────────────────────────────────────────────────────
/**
 * Fetch the boss friend (chat) list.
 */
export async function fetchFriendList(page, opts = {}) {
    const pageNum = opts.pageNum ?? 1;
    const jobId = opts.jobId ?? '0';
    const url = `https://${BOSS_DOMAIN}/wapi/zprelation/friend/getBossFriendListV2.json?page=${pageNum}&status=0&jobId=${jobId}`;
    const data = await bossFetch(page, url, { allowNonZero: opts.allowNonZero });
    if (opts.allowNonZero && data.code !== 0) return data;
    const list = data.zpData?.friendList;
    if (!Array.isArray(list)) {
        throw new CommandExecutionError('Boss friend list response did not include zpData.friendList');
    }
    return list;
}
/**
 * Fetch the recommended candidates (greetRecSortList).
 */
export async function fetchRecommendList(page) {
    const url = `https://${BOSS_DOMAIN}/wapi/zprelation/friend/greetRecSortList`;
    const data = await bossFetch(page, url);
    const list = data.zpData?.friendList;
    if (!Array.isArray(list)) {
        throw new CommandExecutionError('Boss recommend response did not include zpData.friendList');
    }
    return list;
}
/**
 * Find a friend by encryptUid, searching through friend list and optionally greet list.
 * Returns null if not found.

View on GitHub (pinned to 49907e53dc)

Solutions

Update the library to the latest version — BOSS periodically changes zpData shapes and the library tracks them.
Log the full response (OPENCLI_VERBOSE or manual page.evaluate of the URL) to inspect the actual payload shape.
Retry — transient truncation under server load can produce empty zpData.
Adjust query params (valid jobId, pageNum within range) and retry, since odd parameter combos may return atypical bodies.
If the shape consistently differs, patch fetchFriendList to read the new field or file an issue with the captured payload.

Example fix

// before
const list = data.zpData?.friendList;
// after
const list = data.zpData?.friendList ?? data.zpData?.result ?? [];  // tolerate renamed field

Defensive patterns

Strategy: type-guard

Validate before calling

function hasFriendList(data) {
  return !!data && typeof data === 'object' && Array.isArray(data.zpData?.friendList);
}
const probe = await bossFetch(page, friendListUrl, { allowNonZero: true });
if (probe.code === 0 && !hasFriendList(probe)) console.error('zpData shape changed; update the library.');

Type guard

function isFriendList(v) {
  return typeof v === 'object' && v !== null && Array.isArray(v.zpData?.friendList);
}

Try / catch

try {
  const friends = await fetchFriendList(page);
} catch (e) {
  if (e instanceof CommandExecutionError && /zpData\.friendList/.test(e.message)) {
    const raw = await bossFetch(page, friendListUrl, { allowNonZero: true });
    console.error('Unexpected payload:', JSON.stringify(raw).slice(0, 500));
    return []; // or report for library update
  }
  throw e;
}

Prevention

Keep the library updated; BOSS changes zpData shapes over time
Log full payloads with OPENCLI_VERBOSE to spot schema drift early
Retry transient truncations before treating them as schema changes
File an issue with the captured payload if the shape consistently differs

When it happens

Trigger: getBossFriendListV2.json returning code 0 (or allowNonZero with code 0) but without zpData.friendList — e.g. BOSS renamed/reshaped the field, the response was a partially-empty object, or a captcha/limit payload shaped differently.

Common situations: BOSS front-end API version change altering zpData structure; running an outdated library version after a BOSS schema update; jobId/page combos returning empty bodies without the usual array; intermittent server-side truncation under load.

Related errors

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