{"record":{"id":"3f8abdab31acba5c","repo":"mastra-ai/mastra","slug":"invalid-json","errorCode":"INVALID_JSON","errorMessage":"INVALID_JSON: Input JSON must be an object","messagePattern":"INVALID_JSON: Input JSON must be an object","errorType":"error_code","errorClass":"ApiCliError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/api/input.ts","lineNumber":21,"sourceCode":"\nexport type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };\n\nexport function parseInput(descriptor: ApiCommandDescriptor, input?: string): Record<string, unknown> | undefined {\n  if (!descriptor.acceptsInput) return undefined;\n\n  if (!input) {\n    if (descriptor.inputRequired) {\n      throw new ApiCliError('MISSING_INPUT', 'Command requires a single inline JSON input argument', {\n        command: `mastra api ${descriptor.name}`,\n      });\n    }\n    return undefined;\n  }\n\n  try {\n    const parsed = JSON.parse(input);\n    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n      throw new ApiCliError('INVALID_JSON', 'Input JSON must be an object');\n    }\n    return parsed as Record<string, unknown>;\n  } catch (error) {\n    if (error instanceof ApiCliError) throw error;\n    throw new ApiCliError('INVALID_JSON', 'Input must be valid JSON', {\n      message: error instanceof Error ? error.message : String(error),\n    });\n  }\n}\n\nexport function resolvePathParams(\n  descriptor: ApiCommandDescriptor,\n  positionalValues: string[],\n  input?: Record<string, unknown>,\n): Record<string, string> {\n  const params: Record<string, string> = {};\n\n  descriptor.positionals.forEach((name, index) => {","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/api/input.ts#L3-L39","documentation":"The Mastra API CLI parses the inline `--input` JSON argument with JSON.parse and then requires the result to be a plain object. When the parsed value is null, a scalar (string/number/boolean), or an array, parseInput throws INVALID_JSON with 'Input JSON must be an object', because API command inputs are always Record<string, unknown> bodies merged with path params and query values.","triggerScenarios":"Running `mastra api <command> --input 'null'`, `--input '\"text\"'`, `--input '5'`, or `--input '[1,2,3]'` — any value that parses as JSON but is not a non-null, non-array object.","commonSituations":"Users passing a bare JSON array as a body because the endpoint conceptually accepts a list; shell quoting stripping quotes so `--input {}` becomes a literal `{}` string vs `--input '\"x\"'`; copy-pasting an array payload from a REST example; forgetting that the CLI expects a top-level object keyed by field name.","solutions":["Wrap the payload in an object, e.g. --input '{\"items\":[1,2,3]}' instead of --input '[1,2,3]'","Validate with `node -e 'const v=JSON.parse(process.argv[1]); if(!v||Array.isArray(v)||typeof v!==\"object\") throw 0' -- <your-arg>` before invoking","Check the command's schema via the CLI (e.g. a schema/describe subcommand) to see the expected top-level shape","If the endpoint truly accepts an array body, file/inspect a CLI issue — the CLI currently only accepts object inputs"],"exampleFix":"// before\nmastra api agents generate --input '\"Hello\"'\n// after\nmastra api agents generate --input '{\"messages\":\"Hello\"}'","handlingStrategy":"validation","validationCode":"function isValidObjectInput(raw) { try { const v = JSON.parse(raw); return v !== null && typeof v === 'object' && !Array.isArray(v); } catch { return false; } }\nif (!isValidObjectInput(myInput)) { /* fix payload before invoking CLI */ }","typeGuard":"function isPlainObject(v: unknown): v is Record<string, unknown> { return v !== null && typeof v === 'object' && !Array.isArray(v); }","tryCatchPattern":"try { await exec('mastra', ['api', cmd, '--input', raw]); } catch (e) { if (String(e).includes('INVALID_JSON')) { console.error('Input must be a JSON object, e.g. {\"key\": \"value\"}'); } else throw e; }","preventionTips":["Always pass top-level JSON objects in --input, never arrays or scalars","Lint the payload with jq or JSON.parse before invoking the CLI","Quote the argument with single quotes in bash to preserve JSON structure","Consult the command schema/docs for the expected body shape"],"tags":["json","cli","input-validation"],"backgroundTag":"invalid-json-input","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}