mastra-ai/mastra · info · HTTPException

Processor ID is required

Error message

Processor ID is required

What it means

POST /processors/:processorId/execute throws this HTTP 400 when the `processorId` path parameter is missing/empty at handler time. It is a defensive guard even though the route normally enforces the path param via the schema.

Solutions

1. Ensure the processor id is set before building the request URL.
2. Validate the id on the client (non-empty string) before POSTing.
3. Check the URL template resolves correctly — no double slashes or missing segment.

Example fix

// before
await fetch(`/api/processors/${id}/execute`, { method: 'POST', ... });
// after
if (!id) throw new Error('processorId is required');
await fetch(`/api/processors/${encodeURIComponent(id)}/execute`, { method: 'POST', ... });

if (typeof processorId !== 'string' || processorId.trim() === '') {
  throw new Error('processorId must be a non-empty string before calling /processors/:id/execute');
}

function hasProcessorId(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  const res = await fetch(url, options);
  if (res.status === 400) {
    const body = await res.json();
    if (body.message === 'Processor ID is required') throw new Error('Request mis-built: missing path param');
  }
  return await res.json();
} catch (e) {
  console.error(e);
  throw e;
}

When it happens

Trigger: Sending POST /processors//execute (empty path segment), or invoking the handler programmatically without a processorId, causing the falsy check `if (!processorId)` to fire.

Common situations: Client code builds the URL from an undefined/null variable; an id containing only whitespace; template-string interpolation with an unset value; calling the route handler directly in tests with an incomplete context.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Phase is required
• bad request
• Messages array is required
• runId required to observe workflow stream
• Agent ID is required

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/4b9f7b3741f0f423. Report an issue: GitHub.

Appendix: source

Thrown at packages/server/src/server/handlers/processors.ts:209

});

export const EXECUTE_PROCESSOR_ROUTE = createRoute({
  method: 'POST',
  path: '/processors/:processorId/execute',
  responseType: 'json',
  pathParamSchema: processorIdPathParams,
  bodySchema: executeProcessorBodySchema,
  responseSchema: executeProcessorResponseSchema,
  summary: 'Execute processor',
  description: 'Executes a specific processor with the provided input data',
  tags: ['Processors'],
  requiresAuth: true,
  handler: async ({ mastra, processorId, ...bodyParams }) => {
    try {
      const { phase, messages } = bodyParams;

      if (!processorId) {
        throw new HTTPException(400, { message: 'Processor ID is required' });
      }

      if (!phase) {
        throw new HTTPException(400, { message: 'Phase is required' });
      }

      if (!messages || !Array.isArray(messages)) {
        throw new HTTPException(400, { message: 'Messages array is required' });
      }

      // Get the processor from Mastra's registered processors
      let processor;
      try {
        processor = mastra.getProcessorById(processorId);
      } catch {
        // getProcessorById throws if not found, try by key
        const processors = mastra.listProcessors() || {};
        processor = processors[processorId as keyof typeof processors];

View on GitHub (pinned to 75dd419e61)