mastra-ai/mastra · warning · HTTPException

Processor provider with id ${providerId} not found

Error message

Processor provider with id ${providerId} not found

What it means

This HTTP 404 is thrown by GET /processor-providers/:providerId when the configured editor exists but has no processor provider registered under the requested `providerId`. It means the request itself was fine but the provider id is unknown to the editor's provider registry.

Source

Thrown at packages/server/src/server/handlers/processor-providers.ts:75

  responseType: 'json',
  pathParamSchema: processorProviderIdPathParams,
  responseSchema: getProcessorProviderResponseSchema,
  summary: 'Get processor provider details',
  description: 'Returns details about a specific processor provider, including its configuration schema',
  tags: ['Processor Providers'],
  requiresAuth: true,
  handler: async ({ mastra, providerId }) => {
    try {
      const editor = mastra.getEditor();

      if (!editor) {
        throw new HTTPException(500, { message: 'Editor is not configured' });
      }

      const provider = editor.getProcessorProvider(providerId);

      if (!provider) {
        throw new HTTPException(404, { message: `Processor provider with id ${providerId} not found` });
      }

      return {
        ...provider.info,
        availablePhases: provider.availablePhases,
        configSchema: zodToJsonSchema(provider.configSchema) as Record<string, unknown>,
      };
    } catch (error) {
      return handleError(error, 'Error getting processor provider');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Call GET /processor-providers first and use an id from that response.
  2. Check the id registered in your editor configuration matches the requested providerId exactly (case-sensitive).
  3. Ensure the provider is actually added to the editor's providers array in your Mastra setup.
  4. Refresh the Studio/playground state if it cached a stale provider list.

Example fix

// before
const provider = await fetch('/api/processor-providers/my-provider').then(r => r.json());
// after
const { providers } = await fetch('/api/processor-providers').then(r => r.json());
const id = providers.find(p => p.name === 'My Provider')?.id;
const provider = id ? await fetch(`/api/processor-providers/${id}`).then(r => r.json()) : null;
Defensive patterns

Strategy: validation

Validate before calling

const { providers } = await fetch('/api/processor-providers').then(r => r.json());
if (!providers.some(p => p.id === providerId)) {
  throw new Error(`Unknown processor provider: ${providerId}. Available: ${providers.map(p => p.id).join(', ')}`);
}

Type guard

function isKnownProvider(providerId: string, providers: { id: string }[]): providerId is string {
  return providers.some(p => p.id === providerId);
}

Try / catch

try {
  const res = await fetch(`/api/processor-providers/${providerId}`);
  if (res.status === 404) {
    console.warn(`Provider ${providerId} not registered; refreshing list`);
    return null;
  }
  return await res.json();
} catch (e) {
  console.error(e);
  return null;
}

Prevention

When it happens

Trigger: GET /processor-providers/:providerId where `editor.getProcessorProvider(providerId)` returns undefined — e.g. a mistyped provider id in the URL, or a provider registered under a different id than the one requested.

Common situations: The playground UI cached a provider list from before the provider was renamed/removed; the provider is registered only in another environment; client code constructs the id from processor names instead of listing providers first via GET /processor-providers.

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

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