jackwener/OpenCLI · error · CommandExecutionError

expected inbox items array, got ${typeof items} (contract dr

Error message

expected inbox items array, got ${typeof items} (contract drift?)

What it means

clis/slock/inbox.js maps the result of an in-page evaluate to an inbox items array. It tolerates a bare array or an object with an `items` property, but if the normalized value is still not an array it throws this CommandExecutionError, meaning the server/response shape no longer matches the CLI's expected contract.

Source

Thrown at clis/slock/inbox.js:70

  func: async (page, kwargs) => {
    const filter = String(kwargs.filter ?? 'all').toLowerCase();
    if (!FILTERS.includes(filter)) {
      throw new ArgumentError(`--filter must be one of ${FILTERS.join(' | ')} (got "${filter}")`);
    }
    const limit = parsePositiveInteger(kwargs.limit, '--limit', { defaultValue: 30, max: 100 });
    const offset = parseNonNegativeInteger(kwargs.offset, '--offset', { defaultValue: 0 });
    await page.goto(SLOCK_HOME_URL);
    const snippet = buildFetchSnippet({
      method: 'GET',
      path: `/channels/inbox?filter=${encodeURIComponent(filter)}&limit=${limit}&offset=${offset}`,
      serverScoped: true,
      serverIdOverride: kwargs.server,
    });
    const result = await page.evaluate(`(async () => { ${snippet} })()`);
    const data = dispatchEvaluateResult(result);
    const items = Array.isArray(data) ? data : (data.items || []);
    if (!Array.isArray(items)) {
      throw new CommandExecutionError(`expected inbox items array, got ${typeof items} (contract drift?)`);
    }
    return items.map(mapItem);
  },
});

View on GitHub (pinned to 49907e53dc)

Solutions

Update the slock CLI to match the current server response contract (check the /inbox endpoint envelope field name).
Log the raw `data` value before the throw to see what shape actually came back.
Verify authentication/active server is correct so the endpoint returns the real payload rather than an error object.
Retry after checking for server-side upgrades or breaking changes in release notes.

Example fix

// before
const items = Array.isArray(data) ? data : (data.items || []);
// after
const items = Array.isArray(data) ? data : (data.items || data.messages || data.entries || []);

Defensive patterns

Strategy: type-guard

Validate before calling

const data = dispatchEvaluateResult(result);
const candidate = Array.isArray(data) ? data : data?.items;
if (!Array.isArray(candidate)) throw new Error(`unexpected inbox payload: ${JSON.stringify(data).slice(0,200)}`);

Type guard

function isInboxItems(v) { return Array.isArray(v) || (v !== null && typeof v === 'object' && Array.isArray(v.items)); }

Try / catch

try { const items = await inbox(page, kwargs); } catch (e) { if (String(e.message).includes('expected inbox items array')) { console.error('Contract drift — inspect raw payload / update CLI'); } else throw e; }

Prevention

Pin CLI version to the server API version you run against
Log raw evaluate payloads once when integrating a new server
Wrap dispatchEvaluateResult results with array checks before mapping

When it happens

Trigger: Running `inbox` when page.evaluate returns a payload where dispatchEvaluateResult(data) yields neither an array nor an object with an `items` array field — e.g. the API changed its envelope, an error object leaked through dispatchEvaluateResult, or `data.items` itself is an object/null.

Common situations: Server API version drifted from what the CLI expects (envelope renamed from `items` to something else); an auth/permission failure returns an error object the dispatcher doesn't convert; a proxy returns HTML/JSON error bodies instead of the expected response.

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