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.

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)

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 parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Phase is required
• bad request: ${responseText}
• Messages array is required
• runId required to observe workflow stream
• JSON.stringify(errorResponse)

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