jackwener/OpenCLI · error · CommandExecutionError

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

Error message

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

What it means

requirePayloadObject throws this CommandExecutionError when the API response that should be a JSON object is missing, not an object, or is an array. It guards against Atlassian changing a payload shape or a command reading the wrong endpoint, so downstream property access never crashes on undefined.

Source

Thrown at clis/_atlassian/shared.js:248

        if (Array.isArray(value)) {
            for (const item of value) qs.append(key, String(item));
        } else {
            qs.set(key, String(value));
        }
    }
    const s = qs.toString();
    return s ? `?${s}` : '';
}

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`${label} is required`);
    return s;
}

export function requirePayloadObject(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 requirePayloadArray(value, label) {
    if (!Array.isArray(value)) {
        throw new CommandExecutionError(`${label} returned an unexpected payload shape; expected an array.`);
    }
    return value;
}

export function requirePayloadString(value, field, label) {
    if (typeof value !== 'string' && typeof value !== 'number') {
        throw new CommandExecutionError(`${label} did not include a stable ${field}.`);
    }
    const s = String(value).trim();
    if (!s) throw new CommandExecutionError(`${label} did not include a stable ${field}.`);
    return s;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Verify the deployment (ATLASSIAN_DEPLOYMENT=cloud|datacenter) matches the target instance so the expected payload shape is used.
2. Confirm the command/endpoint targets the right resource; a 200 with an unexpected shape often means the wrong REST path was hit.
3. Inspect the raw response with curl to see what the API actually returned.
4. Update the CLI if Atlassian changed the API contract; check for a newer version.

Example fix

// before (cloud base URL used against Data Center, envelope differs)
ATLASSIAN_DEPLOYMENT=auto
// after
ATLASSIAN_DEPLOYMENT=datacenter ATLASSIAN_BASE_URL=https://confluence.corp.com

function looksLikeObjectPayload(v) {
  return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length > 0;
}

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

try {
  const payload = await cmd(args);
} catch (e) {
  if (/unexpected payload shape; expected an object/.test(e.message)) {
    console.error('Response shape mismatch — check ATLASSIAN_DEPLOYMENT (cloud vs datacenter) and CLI version.');
  } else throw e;
}

When it happens

Trigger: An endpoint expected to return {..} returns null, an array, or an error body; API version drift (Data Center vs Cloud payloads differ); hitting the wrong REST path that returns a JSON list.

Common situations: Pointing cloud CLI flags at a Data Center instance (or vice versa) so response envelopes differ; a plugin/macro endpoint returning [] when nothing matches; an intercepted response that is a JSON string rather than object.

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 a
• ${label} did not include a stable ${field}.
• Bilibili ${label} API returned a malformed payload
• 12306 ${endpoint} returned an unexpected payload shape
• ${label} returned a non-JSON response

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