mastra-ai/mastra · warning · HTTPException

Processor not found

Error message

Processor not found

What it means

GET /processors/:processorId throws this HTTP 404 when neither `mastra.getProcessorById(processorId)` nor a lookup by key in `mastra.listProcessors()` finds a processor. The handler tries both strategies before concluding the processor is not registered on the Mastra instance.

Source

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

  responseSchema: serializedProcessorDetailSchema,
  summary: 'Get processor by ID',
  description: 'Returns details for a specific processor including its phases and configurations',
  tags: ['Processors'],
  requiresAuth: true,
  handler: async ({ mastra, processorId }) => {
    try {
      // Get the processor from Mastra's registered processors
      let processorEntry: Processor | ProcessorWorkflow | undefined;
      try {
        processorEntry = mastra.getProcessorById(processorId) as Processor | ProcessorWorkflow;
      } catch {
        // getProcessorById throws if not found, try by key
        const processors = mastra.listProcessors() || {};
        processorEntry = processors[processorId as keyof typeof processors] as Processor | ProcessorWorkflow;
      }

      if (!processorEntry) {
        throw new HTTPException(404, { message: 'Processor not found' });
      }

      // Check if it's a workflow processor
      const isWorkflow = isProcessorWorkflow(processorEntry);

      // Detect phases (handles both individual processors and workflow processors)
      const phases = detectProcessorPhases(processorEntry);

      // Get agent configurations for this processor
      const configs = mastra.getProcessorConfigurations(processorId);
      const agents = mastra.listAgents() || {};
      const configurations = configs.map(c => ({
        agentId: c.agentId,
        agentName: agents[c.agentId]?.name || c.agentId,
        type: c.type,
      }));

      return {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Call GET /processors to list registered processors and confirm the exact id.
2. Register the processor in the Mastra constructor: `new Mastra({ processors: { myProcessor } })`.
3. Verify the server you are querying runs the same Mastra instance that registers the processor.
4. Fix any id mismatch between the processor's `id` property and the registry key used in the processors map.

Example fix

// before
new Mastra({ agents });
// after
new Mastra({ agents, processors: { 'pii-redactor': new PiiRedactor() } });

const processors = await fetch('/api/processors').then(r => r.json());
if (!processors[processorId]) {
  throw new Error(`Processor ${processorId} is not registered. Available: ${Object.keys(processors).join(', ')}`);
}

function processorExists(registry: Record<string, unknown>, id: string): id is string {
  return Object.prototype.hasOwnProperty.call(registry, id);
}

try {
  const res = await fetch(`/api/processors/${processorId}`);
  if (res.status === 404) {
    const available = await fetch('/api/processors').then(r => r.json());
    throw new Error(`Unknown processor. Available: ${Object.keys(available).join(', ')}`);
  }
  return await res.json();
} catch (e) {
  console.error(e);
  return null;
}

When it happens

Trigger: GET /processors/:processorId with a processorId that is neither a registered processor id nor a key in the processors map — e.g. processor never passed to `new Mastra({ processors })`, removed, or the id in the URL is wrong.

Common situations: Typo in the processor id; processor registered on a different Mastra instance/environment than the server is running; renamed processor with stale client references; pointing the playground at a project that registers no processors.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Processor provider with id ${providerId} not found
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData must include either sessionId or c

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