{"record":{"id":"f703aa68f920fabf","repo":"mastra-ai/mastra","slug":"api-key-not-found-for-provider-mastra-set-mastra","errorCode":null,"errorMessage":"API key not found for provider mastra. Set MASTRA_GATEWAY_API_KEY","messagePattern":"API key not found for provider mastra\\. Set MASTRA_GATEWAY_API_KEY","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/embedding-router.ts","lineNumber":193,"sourceCode":"        }\n        const [providerId, modelId] = parts as [string, string];\n        normalizedConfig = {\n          providerId,\n          modelId,\n          url: config.url,\n          apiKey: config.apiKey,\n          headers: config.headers,\n        };\n      }\n    }\n\n    this.provider = normalizedConfig.providerId;\n    this.modelId = normalizedConfig.modelId;\n\n    if (normalizedConfig.providerId === MASTRA_GATEWAY_ID) {\n      const apiKey = normalizedConfig.apiKey ?? process.env['MASTRA_GATEWAY_API_KEY'];\n      if (!apiKey) {\n        throw new Error('API key not found for provider mastra. Set MASTRA_GATEWAY_API_KEY');\n      }\n\n      this.providerModel = createOpenAICompatible({\n        name: MASTRA_GATEWAY_ID,\n        apiKey,\n        baseURL: getMastraGatewayBaseUrl(normalizedConfig.url),\n        headers: {\n          'User-Agent': MASTRA_USER_AGENT,\n          ...normalizedConfig.headers,\n        },\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,","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/embedding-router.ts#L175-L211","documentation":"When the model routes through the Mastra gateway (providerId === \"mastra\"), the router needs an API key. It takes normalizedConfig.apiKey, else falls back to the MASTRA_GATEWAY_API_KEY environment variable; if neither is set the constructor throws. This is fail-fast so authentication failures surface at construction, not at first request.","triggerScenarios":"new EmbeddingRouter(\"mastra/openai/text-embedding-3-small\") (or equivalent object/id config) with no `apiKey` option and MASTRA_GATEWAY_API_KEY unset in the environment.","commonSituations":"Fresh checkout where .env wasn't loaded (dotenv not called before construction); CI/CD secrets not configured; key defined under a different env var name (e.g. MASTRA_API_KEY); server process started without the env file.","solutions":["Set the MASTRA_GATEWAY_API_KEY environment variable to your Mastra gateway key.","Pass apiKey explicitly: new EmbeddingRouter({ id: \"mastra/...\", apiKey: process.env.MASTRA_GATEWAY_API_KEY }).","Ensure dotenv/config loads .env before the EmbeddingRouter is constructed (import order matters).","Check for env var name typos and that the process actually sees the variable (console.log/process.env check)."],"exampleFix":"// before (key missing)\nnew EmbeddingRouter({ id: \"mastra/openai/text-embedding-3-small\" });\n// after\nnew EmbeddingRouter({\n  id: \"mastra/openai/text-embedding-3-small\",\n  apiKey: process.env.MASTRA_GATEWAY_API_KEY,\n});","handlingStrategy":"try-catch","validationCode":"if (!config.apiKey && !process.env.MASTRA_GATEWAY_API_KEY) {\n  throw new Error('Set MASTRA_GATEWAY_API_KEY before creating a mastra gateway embedding router');\n}","typeGuard":"function hasMastraKey(config) {\n  return typeof config.apiKey === 'string' && config.apiKey.length > 0 || typeof process.env.MASTRA_GATEWAY_API_KEY === 'string' && process.env.MASTRA_GATEWAY_API_KEY.length > 0;\n}","tryCatchPattern":"try {\n  router = new EmbeddingRouter(mastraConfig);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('MASTRA_GATEWAY_API_KEY')) {\n    console.error('Missing MASTRA_GATEWAY_API_KEY env var; load .env or pass apiKey');\n  } else throw e;\n}","preventionTips":["Load .env at the true process entry point before importing modules that construct routers.","Fail fast at startup: assert required env vars exist before serving traffic.","Pass apiKey explicitly in serverless/CI where env inheritance is unreliable."],"tags":["authentication","api-key","environment","configuration"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}