{"record":{"id":"b7e2774de317291b","repo":"paperclipai/paperclip","slug":"payload-must-be-a-json-object","errorCode":null,"errorMessage":"--payload must be a JSON object","messagePattern":"--payload must be a JSON object","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/agent.ts","lineNumber":866,"sourceCode":"              }\n            }\n          }\n          console.log(\"\");\n          console.log(\"# Run this in your shell before launching codex/claude:\");\n          console.log(exportsText);\n        } catch (err) {\n          handleCommandError(err);\n        }\n      }),\n    { includeCompany: false },\n  );\n}\n\nfunction parseJsonObject(value: string | undefined): Record<string, unknown> | undefined {\n  if (value === undefined) return undefined;\n  const parsed = JSON.parse(value) as unknown;\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    throw new Error(\"--payload must be a JSON object\");\n  }\n  return parsed as Record<string, unknown>;\n}\n\nfunction parseJson(value: string): unknown {\n  return JSON.parse(value) as unknown;\n}\n\nfunction parseCsv(value: string | undefined): string[] {\n  if (!value) return [];\n  return value.split(\",\").map((part) => part.trim()).filter(Boolean);\n}\n","sourceCodeStart":848,"sourceCodeEnd":879,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/agent.ts#L848-L879","documentation":"Thrown by parseJsonObject() used by `paperclipai agent wake` when --payload parses as valid JSON but is not a plain object (it is a number, string, array, or boolean). JSON.parse itself succeeded; the runtime type check rejected the result. A malformed JSON string would instead surface as a JSON.parse SyntaxError (not this message).","triggerScenarios":"Passing --payload '[1,2,3]' (array), --payload '\"x\"' (string), --payload '42' (number), or --payload 'true' to `agent wake`. The wakeup contract requires an object payload.","commonSituations":"User wrapped a single value in quotes thinking it becomes an object. User passed a JSON array of items. User forgot the surrounding braces for key/value pairs.","solutions":["Wrap the value as an object: --payload '{\"key\":\"value\"}'.","If you have no payload, omit --payload entirely (parseJsonObject returns undefined for no value).","Validate locally first: `echo '{}' | jq empty` then pass it."],"exampleFix":"// before\npaperclipai agent wake agt_1 --payload '[\"a\",\"b\"]'\n// after\npaperclipai agent wake agt_1 --payload '{\"items\":[\"a\",\"b\"]}'","handlingStrategy":"validation","validationCode":"function asJsonObject(value: string | undefined): Record<string, unknown> | undefined {\n  if (value === undefined) return undefined;\n  const parsed = JSON.parse(value) as unknown;\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    throw new Error(`--payload must be a JSON object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`);\n  }\n  return parsed as Record<string, unknown>;\n}","typeGuard":"function isPlainObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}","tryCatchPattern":"try { parseJsonObject(opts.payload); }\ncatch (err) {\n  const msg = err instanceof Error ? err.message : String(err);\n  if (msg === '--payload must be a JSON object') {\n    console.error('Pass --payload as a JSON object, e.g. --payload \\'{}\\'');\n    process.exit(2);\n  }\n  throw err; // JSON.parse syntax error\n}","preventionTips":["Omit --payload entirely when no payload is needed.","Validate JSON with `jq empty` before passing it on the CLI.","Use double quotes for keys and string values (shell-safe).","Wrap non-object values in an object key before sending."],"tags":["cli","agent","json","validation","wake"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}