mastra-ai/mastra · error

Unknown provider: ${normalizedConfig.providerId}

Error message

Unknown provider: ${normalizedConfig.providerId}

What it means

For non-mastra providers, the constructor looks up the providerId in the GatewayRegistry to find its configuration (env var name, base URL). If the registry has no entry for that providerId, it throws. The registry only knows a fixed set of supported gateway providers.

Source

Thrown at packages/core/src/llm/model/embedding-router.ts:221

        },
      }).embeddingModel(normalizedConfig.modelId);
    } else if (normalizedConfig.url) {
      // If custom URL is provided, skip provider registry validation
      // and use the provided API key (or empty string if not provided)
      const apiKey = normalizedConfig.apiKey || '';
      this.providerModel = createOpenAICompatible({
        name: normalizedConfig.providerId,
        apiKey,
        baseURL: normalizedConfig.url,
        headers: normalizedConfig.headers,
      }).embeddingModel(normalizedConfig.modelId);
    } else {
      // Get provider config from registry
      const registry = GatewayRegistry.getInstance();
      const providerConfig = registry.getProviderConfig(normalizedConfig.providerId);

      if (!providerConfig) {
        throw new Error(`Unknown provider: ${normalizedConfig.providerId}`);
      }

      // Get API key from config or environment
      let apiKey = normalizedConfig.apiKey;
      if (!apiKey) {
        const apiKeyEnvVar = providerConfig.apiKeyEnvVar;
        if (Array.isArray(apiKeyEnvVar)) {
          // Try each possible environment variable
          for (const envVar of apiKeyEnvVar) {
            apiKey = process.env[envVar];
            if (apiKey) break;
          }
        } else {
          apiKey = process.env[apiKeyEnvVar];
        }
      }

      if (!apiKey) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a registered provider id exactly as spelled in the registry (e.g. "openai", "google", "azure-openai").
2. Check the GatewayRegistry for the list of supported provider ids and match casing (ids are typically lowercase).
3. For custom endpoints, pass explicit url/apiKey via object config if supported rather than relying on registry lookup.
4. Verify you're not confusing LLM gateway provider ids with embedding router provider ids.

Example fix

// before
new EmbeddingRouter("OpenAI/text-embedding-3-small");
// after
new EmbeddingRouter("openai/text-embedding-3-small");

import { GatewayRegistry } from '@mastra/core/llm/model/gateway-resolver';
const known = GatewayRegistry.getInstance().getProviderConfig(providerId);
if (!known) throw new Error(`Provider "${providerId}" is not registered; check spelling/casing`);

const isRegisteredProvider = (id) => GatewayRegistry.getInstance().getProviderConfig(id) != null;

try {
  router = new EmbeddingRouter(`${providerId}/${modelId}`);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown provider:')) {
    console.error(`"${providerId}" not in registry; use a registered provider id`);
  } else throw e;
}

When it happens

Trigger: new EmbeddingRouter("not-a-provider/text-embed") or a misspelled id like "OpenAI/text-embedding-3-small" / "open-ai/..." where providerId has no GatewayRegistry entry.

Common situations: Typos or casing mismatches in provider id; using a provider supported by @mastra/core LLM routing but not in the embedding gateway registry; custom/self-hosted providers that need explicit url config instead of registry lookup.

Related errors

• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for
• terminationGraceMs must be greater than zero.

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