API key not found for provider mastra. Set MASTRA_GATEWAY_AP

Error message

API key not found for provider mastra. Set MASTRA_GATEWAY_API_KEY

What it means

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.

Source

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

        }
        const [providerId, modelId] = parts as [string, string];
        normalizedConfig = {
          providerId,
          modelId,
          url: config.url,
          apiKey: config.apiKey,
          headers: config.headers,
        };
      }
    }

    this.provider = normalizedConfig.providerId;
    this.modelId = normalizedConfig.modelId;

    if (normalizedConfig.providerId === MASTRA_GATEWAY_ID) {
      const apiKey = normalizedConfig.apiKey ?? process.env['MASTRA_GATEWAY_API_KEY'];
      if (!apiKey) {
        throw new Error('API key not found for provider mastra. Set MASTRA_GATEWAY_API_KEY');
      }

      this.providerModel = createOpenAICompatible({
        name: MASTRA_GATEWAY_ID,
        apiKey,
        baseURL: getMastraGatewayBaseUrl(normalizedConfig.url),
        headers: {
          'User-Agent': MASTRA_USER_AGENT,
          ...normalizedConfig.headers,
        },
      }).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,

View on GitHub (pinned to 75dd419e61)

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).

Example fix

// before (key missing)
new EmbeddingRouter({ id: "mastra/openai/text-embedding-3-small" });
// after
new EmbeddingRouter({
  id: "mastra/openai/text-embedding-3-small",
  apiKey: process.env.MASTRA_GATEWAY_API_KEY,
});

Defensive patterns

Strategy: try-catch

Validate before calling

if (!config.apiKey && !process.env.MASTRA_GATEWAY_API_KEY) {
  throw new Error('Set MASTRA_GATEWAY_API_KEY before creating a mastra gateway embedding router');
}

Type guard

function hasMastraKey(config) {
  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;
}

Try / catch

try {
  router = new EmbeddingRouter(mastraConfig);
} catch (e) {
  if (e instanceof Error && e.message.includes('MASTRA_GATEWAY_API_KEY')) {
    console.error('Missing MASTRA_GATEWAY_API_KEY env var; load .env or pass apiKey');
  } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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