API key not found for provider ${normalizedConfig.providerId

Error message

API key not found for provider ${normalizedConfig.providerId}. Set ${envVarDisplay}

What it means

After resolving the provider's configured apiKeyEnvVar name(s) from the registry, the router checks config apiKey first, then those environment variables. If none is set, it throws, listing the expected env var(s). This ensures requests are never sent without credentials.

Source

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

      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) {
        const envVarDisplay = Array.isArray(providerConfig.apiKeyEnvVar)
          ? providerConfig.apiKeyEnvVar.join(' or ')
          : providerConfig.apiKeyEnvVar;
        throw new Error(`API key not found for provider ${normalizedConfig.providerId}. Set ${envVarDisplay}`);
      }

      // Initialize the provider model directly in constructor
      if (normalizedConfig.providerId === 'openai') {
        this.providerModel = createOpenAI({ apiKey }).embeddingModel(normalizedConfig.modelId);
      } else if (normalizedConfig.providerId === 'google') {
        this.providerModel = createGoogleGenerativeAI({ apiKey }).embeddingModel(normalizedConfig.modelId);
      } else {
        // Use OpenAI-compatible provider for other providers
        if (!providerConfig.url) {
          throw new Error(`Provider ${normalizedConfig.providerId} does not have a URL configured`);
        }
        this.providerModel = createOpenAICompatible({
          name: normalizedConfig.providerId,
          apiKey,
          baseURL: providerConfig.url,
        }).embeddingModel(normalizedConfig.modelId);
      }

View on GitHub (pinned to 75dd419e61)

Solutions

Set the env var named in the error message (e.g. export OPENAI_API_KEY=sk-...).
Pass apiKey directly in the constructor config object.
Ensure .env is loaded (dotenv) before any EmbeddingRouter is instantiated.
For providers accepting multiple env vars, set at least one of the listed alternatives.

Example fix

// before
const router = new EmbeddingRouter("openai/text-embedding-3-small"); // OPENAI_API_KEY unset
// after
const router = new EmbeddingRouter({
  providerId: "openai",
  modelId: "text-embedding-3-small",
  apiKey: process.env.OPENAI_API_KEY,
});

Defensive patterns

Strategy: try-catch

Validate before calling

const envVars = ['OPENAI_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY'];
if (!config.apiKey && envVars.every((v) => !process.env[v])) {
  throw new Error(`Set one of ${envVars.join(' or ')} for provider ${providerId}`);
}

Type guard

const hasApiKey = (config) => typeof config?.apiKey === 'string' && config.apiKey.length > 0;

Try / catch

try {
  router = new EmbeddingRouter(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('API key not found for provider')) {
    console.error(`Missing provider API key: ${e.message}`); // shows which env var to set
    process.exit(1);
  } else throw e;
}

Prevention

Document and automate required env vars per deployment (env templates, secret managers).
Run an env-var presence check at application boot.
Never rely on shell-profile env vars for services/CI; inject them explicitly.

When it happens

Trigger: new EmbeddingRouter("openai/text-embedding-3-small") without OPENAI_API_KEY set (and no apiKey option); google models without the Google API key env var; array-valued apiKeyEnvVar providers where none of the alternatives is present.

Common situations: Key set only in the shell profile but the app runs under a service manager/CI without it; .env not loaded before construction; wrong var name (e.g. OPEN_AI_API_KEY vs OPENAI_API_KEY); using the embedding router in tests where env is sanitized.

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/b70d2908f5f3c750. Report an issue: GitHub.