{"record":{"id":"6ac840b686a29b1d","repo":"mastra-ai/mastra","slug":"messages-array-is-required","errorCode":null,"errorMessage":"Messages array is required","messagePattern":"Messages array is required","errorType":"validation","errorClass":"HTTPException","httpStatus":400,"severity":"info","filePath":"packages/server/src/server/handlers/processors.ts","lineNumber":217,"sourceCode":"  responseSchema: executeProcessorResponseSchema,\n  summary: 'Execute processor',\n  description: 'Executes a specific processor with the provided input data',\n  tags: ['Processors'],\n  requiresAuth: true,\n  handler: async ({ mastra, processorId, ...bodyParams }) => {\n    try {\n      const { phase, messages } = bodyParams;\n\n      if (!processorId) {\n        throw new HTTPException(400, { message: 'Processor ID is required' });\n      }\n\n      if (!phase) {\n        throw new HTTPException(400, { message: 'Phase is required' });\n      }\n\n      if (!messages || !Array.isArray(messages)) {\n        throw new HTTPException(400, { message: 'Messages array is required' });\n      }\n\n      // Get the processor from Mastra's registered processors\n      let processor;\n      try {\n        processor = mastra.getProcessorById(processorId);\n      } catch {\n        // getProcessorById throws if not found, try by key\n        const processors = mastra.listProcessors() || {};\n        processor = processors[processorId as keyof typeof processors];\n      }\n\n      if (!processor) {\n        throw new HTTPException(404, { message: 'Processor not found' });\n      }\n\n      const messageList = new MessageList();\n      messageList.add(messages as unknown as MessageInput[], 'input');","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/processors.ts#L199-L235","documentation":"POST /processors/:processorId/execute throws this HTTP 400 when the `messages` body field is missing or is not an array. The handler feeds `messages` into a MessageList before invoking the processor, so it must be an array of message objects.","triggerScenarios":"POST /processors/:id/execute with `{ phase: 'input' }` only, or with `messages` set to a single object/string/null instead of an array — the guard is `if (!messages || !Array.isArray(messages))`.","commonSituations":"Sending one message object directly instead of wrapping it in an array; null messages when the caller had no conversation history; a serialization bug flattening the array client-side; hand-written curl tests omitting messages.","solutions":["Wrap messages in an array: `\"messages\": [{ role: 'user', content: '...' }]`.","Ensure each entry is a valid message shape (role + content) accepted by MessageList.","Default to an empty array client-side when there is no history, if the endpoint contract allows it."],"exampleFix":"// before\nbody: JSON.stringify({ phase: 'input', messages: { role: 'user', content: 'hi' } })\n// after\nbody: JSON.stringify({ phase: 'input', messages: [{ role: 'user', content: 'hi' }] })","handlingStrategy":"validation","validationCode":"if (!Array.isArray(messages)) {\n  throw new Error('messages must be an array of message objects before calling processor execute');\n}\nfor (const m of messages) {\n  if (typeof m !== 'object' || m === null || !('role' in m)) throw new Error('invalid message shape');\n}","typeGuard":"function isMessageArray(v: unknown): v is Array<{ role: string; content: unknown }> {\n  return Array.isArray(v) && v.every(m => typeof m === 'object' && m !== null && 'role' in m);\n}","tryCatchPattern":"try {\n  const res = await fetch(url, { method: 'POST', body: JSON.stringify({ phase, messages }) });\n  if (res.status === 400 && (await res.json()).message === 'Messages array is required') {\n    throw new Error('Client bug: messages must be an array');\n  }\n  return await res.json();\n} catch (e) {\n  console.error(e);\n  throw e;\n}","preventionTips":["Always send messages as an array, even with a single message or empty history.","Type request bodies with the executeProcessorBodySchema shape.","Sanity-check JSON payloads in curl/Postman against the endpoint's body schema."],"tags":["mastra-server","validation","http-400","messages"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}