{"record":{"id":"2b252fd432804690","repo":"jackwener/OpenCLI","slug":"label-returned-an-unexpected-payload-shape-exp-2b252f","errorCode":null,"errorMessage":"${label} returned an unexpected payload shape; expected an array.","messagePattern":"(.+?) returned an unexpected payload shape; expected an array\\.","errorType":"validation","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/_atlassian/shared.js","lineNumber":255,"sourceCode":"    return s ? `?${s}` : '';\n}\n\nexport function requireString(value, label) {\n    const s = String(value ?? '').trim();\n    if (!s) throw new ArgumentError(`${label} is required`);\n    return s;\n}\n\nexport function requirePayloadObject(value, label) {\n    if (!value || typeof value !== 'object' || Array.isArray(value)) {\n        throw new CommandExecutionError(`${label} returned an unexpected payload shape; expected an object.`);\n    }\n    return value;\n}\n\nexport function requirePayloadArray(value, label) {\n    if (!Array.isArray(value)) {\n        throw new CommandExecutionError(`${label} returned an unexpected payload shape; expected an array.`);\n    }\n    return value;\n}\n\nexport function requirePayloadString(value, field, label) {\n    if (typeof value !== 'string' && typeof value !== 'number') {\n        throw new CommandExecutionError(`${label} did not include a stable ${field}.`);\n    }\n    const s = String(value).trim();\n    if (!s) throw new CommandExecutionError(`${label} did not include a stable ${field}.`);\n    return s;\n}\n\nexport function requireNonEmptyRows(rows, label, hint) {\n    if (!rows.length) throw new EmptyResultError(label, hint);\n    return rows;\n}\n","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/_atlassian/shared.js#L237-L273","documentation":"requirePayloadArray throws this CommandExecutionError when an API response expected to be a JSON array is not an array. It protects row-iterating commands (search results, page lists) from crashing on object/null payloads.","triggerScenarios":"A search/list endpoint returns {results:[...]} while the caller expected a bare array (or vice versa); the endpoint returns an error object; Cloud vs Data Center response envelope mismatch.","commonSituations":"Version drift between Atlassian Cloud and Data Center list responses; a wrapped response shape after an API upgrade; hitting a search endpoint that returns an object envelope instead of a list.","solutions":["Check the deployment mode (cloud vs datacenter) matches your instance — the two return differently shaped list payloads.","Inspect the raw JSON with curl and confirm which field actually holds the array (often .results or .values).","Update the opencli Atlassian adapter if Atlassian changed the response shape.","Ensure the query targets a list endpoint, not a single-resource endpoint."],"exampleFix":"// before (expects bare array but v2 returns envelope)\nconst rows = requirePayloadArray(body, 'search');\n// after\nconst rows = requirePayloadArray(body.results ?? body, 'search');","handlingStrategy":"type-guard","validationCode":"function toRows(body) {\n  if (Array.isArray(body)) return body;\n  if (isRecord(body) && Array.isArray(body.results)) return body.results;\n  if (isRecord(body) && Array.isArray(body.values)) return body.values;\n  throw new Error('No array found in response');\n}","typeGuard":"function isNonEmptyArray(v) { return Array.isArray(v); }","tryCatchPattern":"try {\n  const rows = await listCmd(args);\n} catch (e) {\n  if (/unexpected payload shape; expected an array/.test(e.message)) {\n    console.error('List payload was not an array — inspect raw JSON for the results envelope field.');\n  } else throw e;\n}","preventionTips":["Normalize both bare-array and envelope ({results:[]}) shapes in wrapper code.","Verify Cloud vs Data Center list response shapes once per environment.","Pin the API version used by your scripts.","Add integration tests over real (read-only) endpoints for list commands."],"tags":["validation","payload","schema","array","atlassian"],"backgroundTag":"schema-validation-failed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}