{"record":{"id":"d57842dbd2453435","repo":"jackwener/OpenCLI","slug":"label-returned-an-unexpected-payload-shape-exp","errorCode":null,"errorMessage":"${label} returned an unexpected payload shape; expected an object.","messagePattern":"(.+?) returned an unexpected payload shape; expected an object\\.","errorType":"validation","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/_atlassian/shared.js","lineNumber":248,"sourceCode":"        if (Array.isArray(value)) {\n            for (const item of value) qs.append(key, String(item));\n        } else {\n            qs.set(key, String(value));\n        }\n    }\n    const s = qs.toString();\n    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;","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/_atlassian/shared.js#L230-L266","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the deployment (ATLASSIAN_DEPLOYMENT=cloud|datacenter) matches the target instance so the expected payload shape is used.","Confirm the command/endpoint targets the right resource; a 200 with an unexpected shape often means the wrong REST path was hit.","Inspect the raw response with curl to see what the API actually returned.","Update the CLI if Atlassian changed the API contract; check for a newer version."],"exampleFix":"// before (cloud base URL used against Data Center, envelope differs)\nATLASSIAN_DEPLOYMENT=auto\n// after\nATLASSIAN_DEPLOYMENT=datacenter ATLASSIAN_BASE_URL=https://confluence.corp.com","handlingStrategy":"type-guard","validationCode":"function looksLikeObjectPayload(v) {\n  return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length > 0;\n}","typeGuard":"function isRecord(v) { return typeof v === 'object' && v !== null && !Array.isArray(v); }","tryCatchPattern":"try {\n  const payload = await cmd(args);\n} catch (e) {\n  if (/unexpected payload shape; expected an object/.test(e.message)) {\n    console.error('Response shape mismatch — check ATLASSIAN_DEPLOYMENT (cloud vs datacenter) and CLI version.');\n  } else throw e;\n}","preventionTips":["Set ATLASSIAN_DEPLOYMENT explicitly to match your instance type.","Keep the CLI/adapter updated when Atlassian announces API changes.","Spot-check raw responses with curl when integrating a new endpoint.","Write a smoke test asserting payload shape for critical commands."],"tags":["validation","payload","schema","atlassian","json"],"backgroundTag":"schema-validation-failed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}