mastra-ai/mastra · error · Error

Missing environment variable ${envVarName} required to build

Error message

Missing environment variable ${envVarName} required to build provider URL

What it means

A provider URL template in the models.dev registry contains a ${VAR} placeholder, and interpolateUrlTemplate could not resolve that variable from the supplied env or process.env. A plain Error is thrown because a required provider base-URL environment variable is missing. The model's provider simply isn't configured in this environment.

Source

Thrown at packages/core/src/llm/model/gateways/models-dev.ts:75

  if (!envVars?.length) return fallbackEnvVar;

  const suffixPreferences = ['_API_TOKEN', '_API_KEY', '_TOKEN', '_KEY', '_PAT'];

  for (const suffix of suffixPreferences) {
    const preferredEnvVar = envVars.find(envVar => envVar.endsWith(suffix));
    if (preferredEnvVar) return preferredEnvVar;
  }

  return envVars[0] || fallbackEnvVar;
}

function interpolateUrlTemplate(url: string, envVars?: typeof process.env): string {
  return url.replace(/\$\{([^}]+)\}/g, (_match, envVarName: string) => {
    const key = envVarName.trim();
    const value = envVars?.[key] ?? process.env[key];

    if (value === undefined || value === null) {
      throw new Error(`Missing environment variable ${envVarName} required to build provider URL`);
    }

    return value;
  });
}

function resolveApiKeyFromEnv(apiKeyEnvVar: ProviderConfig['apiKeyEnvVar']): string | undefined {
  const envVars = Array.isArray(apiKeyEnvVar) ? apiKeyEnvVar : [apiKeyEnvVar];

  for (const envVar of envVars) {
    const apiKey = process.env[envVar];
    if (apiKey) return apiKey;
  }
}

// Provider-specific overrides for URL, npm package, and other config.
// These take priority over what models.dev returns (e.g. correct base URLs, SDK packages).
// This constant is ONLY used during generation in fetchProviders() to determine

View on GitHub (pinned to 75dd419e61)

Solutions

Set the named environment variable shown in the error message (e.g. AZURE_OPENAI_ENDPOINT).
Pass envVars explicitly to the gateway/url builder if not relying on process.env.
Use a provider whose URL needs no interpolation, or supply a custom base URL.
Fix typos between the template placeholder name and the actual env var name.

Example fix

// before
// env: nothing set; template https://${AZURE_OPENAI_ENDPOINT}/openai/v1
// after
process.env.AZURE_OPENAI_ENDPOINT = 'my-resource.openai.azure.com';
// or: new ModelsDevGateway({ envVars: { AZURE_OPENAI_ENDPOINT: 'my-resource.openai.azure.com' } })

Defensive patterns

Strategy: validation

Validate before calling

const requiredVars = [...urlTemplate.matchAll(/\$\{([^}]+)\}/g)].map(m => m[1].trim());
const missing = requiredVars.filter(k => !process.env[k]);
if (missing.length) throw new Error(`Missing env vars for provider URL: ${missing.join(', ')}`);

Prevention

Document and set the endpoint env vars each provider URL template requires.
Validate all referenced env vars at startup, not at request time.
Use .env.example listing required variables per provider.
Pass explicit envVars to the gateway in tests to avoid process.env dependence.

When it happens

Trigger: Calling buildUrl (via getBaseUrl/url resolution) for a provider whose models.dev URL template references an env var (e.g. ${AZURE_OPENAI_ENDPOINT}) that is undefined or null.

Common situations: Using an Azure/Azure-like provider whose endpoint must be supplied via env; self-hosted/OpenAI-compatible providers requiring a base URL env; Docker/CI environment missing the variable; typo in the env var name.

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