{"record":{"id":"9540f2ba35d9b5c5","repo":"mastra-ai/mastra","slug":"phase-is-required","errorCode":null,"errorMessage":"Phase is required","messagePattern":"Phase is required","errorType":"validation","errorClass":"HTTPException","httpStatus":400,"severity":"info","filePath":"packages/server/src/server/handlers/processors.ts","lineNumber":213,"sourceCode":"  path: '/processors/:processorId/execute',\n  responseType: 'json',\n  pathParamSchema: processorIdPathParams,\n  bodySchema: executeProcessorBodySchema,\n  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' });","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/processors.ts#L195-L231","documentation":"POST /processors/:processorId/execute throws this HTTP 400 when the request body omits the `phase` field. The execute endpoint needs to know which processor phase (`input`, `inputStep`, `outputResult`, `outputStep`, etc.) to run.","triggerScenarios":"POST /processors/:id/execute with a body like `{ messages: [...] }` but no `phase` key, or `phase: undefined` from an unset variable in client code.","commonSituations":"Copy-pasting an execute call from another endpoint that has no phase concept; client SDK version mismatch where phase moved into a nested object; forgetting phase when testing the endpoint with curl/Postman.","solutions":["Add `phase` to the JSON body, e.g. `\"phase\": \"input\"`.","Use a phase the processor actually implements (check GET /processors/:id for its `phases` list).","Note that `outputStream` is rejected separately — for streaming phases use the streaming path instead."],"exampleFix":"// before\nawait fetch(url, { method: 'POST', body: JSON.stringify({ messages }) });\n// after\nawait fetch(url, { method: 'POST', body: JSON.stringify({ phase: 'input', messages }) });","handlingStrategy":"validation","validationCode":"const VALID_PHASES = ['input', 'inputStep', 'outputResult', 'outputStep'];\nif (!VALID_PHASES.includes(phase)) {\n  throw new Error(`phase must be one of ${VALID_PHASES.join(', ')} before executing a processor`);\n}","typeGuard":"type ProcessorPhase = 'input' | 'inputStep' | 'outputResult' | 'outputStep';\nfunction isValidPhase(p: unknown): p is ProcessorPhase {\n  return typeof p === 'string' && ['input', 'inputStep', 'outputResult', 'outputStep'].includes(p);\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 === 'Phase is required') {\n    throw new Error('Client bug: phase omitted from execute body');\n  }\n  return await res.json();\n} catch (e) {\n  console.error(e);\n  throw e;\n}","preventionTips":["Type the execute request body with a ProcessorPhase union so TypeScript enforces the field.","Check the processor's `phases` from GET /processors/:id before choosing one.","Remember outputStream is not directly executable via this endpoint."],"tags":["mastra-server","validation","http-400","bad-request"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}