{"record":{"id":"983bfb9d644182d0","repo":"mastra-ai/mastra","slug":"unknown-provider-normalizedconfig-providerid","errorCode":null,"errorMessage":"Unknown provider: ${normalizedConfig.providerId}","messagePattern":"Unknown provider: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/embedding-router.ts","lineNumber":221,"sourceCode":"        },\n      }).embeddingModel(normalizedConfig.modelId);\n    } else if (normalizedConfig.url) {\n      // If custom URL is provided, skip provider registry validation\n      // and use the provided API key (or empty string if not provided)\n      const apiKey = normalizedConfig.apiKey || '';\n      this.providerModel = createOpenAICompatible({\n        name: normalizedConfig.providerId,\n        apiKey,\n        baseURL: normalizedConfig.url,\n        headers: normalizedConfig.headers,\n      }).embeddingModel(normalizedConfig.modelId);\n    } else {\n      // Get provider config from registry\n      const registry = GatewayRegistry.getInstance();\n      const providerConfig = registry.getProviderConfig(normalizedConfig.providerId);\n\n      if (!providerConfig) {\n        throw new Error(`Unknown provider: ${normalizedConfig.providerId}`);\n      }\n\n      // Get API key from config or environment\n      let apiKey = normalizedConfig.apiKey;\n      if (!apiKey) {\n        const apiKeyEnvVar = providerConfig.apiKeyEnvVar;\n        if (Array.isArray(apiKeyEnvVar)) {\n          // Try each possible environment variable\n          for (const envVar of apiKeyEnvVar) {\n            apiKey = process.env[envVar];\n            if (apiKey) break;\n          }\n        } else {\n          apiKey = process.env[apiKeyEnvVar];\n        }\n      }\n\n      if (!apiKey) {","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/embedding-router.ts#L203-L239","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a registered provider id exactly as spelled in the registry (e.g. \"openai\", \"google\", \"azure-openai\").","Check the GatewayRegistry for the list of supported provider ids and match casing (ids are typically lowercase).","For custom endpoints, pass explicit url/apiKey via object config if supported rather than relying on registry lookup.","Verify you're not confusing LLM gateway provider ids with embedding router provider ids."],"exampleFix":"// before\nnew EmbeddingRouter(\"OpenAI/text-embedding-3-small\");\n// after\nnew EmbeddingRouter(\"openai/text-embedding-3-small\");","handlingStrategy":"validation","validationCode":"import { GatewayRegistry } from '@mastra/core/llm/model/gateway-resolver';\nconst known = GatewayRegistry.getInstance().getProviderConfig(providerId);\nif (!known) throw new Error(`Provider \"${providerId}\" is not registered; check spelling/casing`);","typeGuard":"const isRegisteredProvider = (id) => GatewayRegistry.getInstance().getProviderConfig(id) != null;","tryCatchPattern":"try {\n  router = new EmbeddingRouter(`${providerId}/${modelId}`);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unknown provider:')) {\n    console.error(`\"${providerId}\" not in registry; use a registered provider id`);\n  } else throw e;\n}","preventionTips":["Keep a whitelist of valid provider ids in app config and validate inputs against it.","Always lowercase provider ids from user input or external sources.","Check the GatewayRegistry when upgrading @mastra/core, as supported providers can change."],"tags":["configuration","validation","provider-registry"],"backgroundTag":"unknown-provider","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}