{"record":{"id":"9e5009da0bbf8717","repo":"mastra-ai/mastra","slug":"missing-environment-variable-envvarname-require","errorCode":null,"errorMessage":"Missing environment variable ${envVarName} required to build provider URL","messagePattern":"Missing environment variable (.+?) required to build provider URL","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/gateways/models-dev.ts","lineNumber":75,"sourceCode":"  if (!envVars?.length) return fallbackEnvVar;\n\n  const suffixPreferences = ['_API_TOKEN', '_API_KEY', '_TOKEN', '_KEY', '_PAT'];\n\n  for (const suffix of suffixPreferences) {\n    const preferredEnvVar = envVars.find(envVar => envVar.endsWith(suffix));\n    if (preferredEnvVar) return preferredEnvVar;\n  }\n\n  return envVars[0] || fallbackEnvVar;\n}\n\nfunction interpolateUrlTemplate(url: string, envVars?: typeof process.env): string {\n  return url.replace(/\\$\\{([^}]+)\\}/g, (_match, envVarName: string) => {\n    const key = envVarName.trim();\n    const value = envVars?.[key] ?? process.env[key];\n\n    if (value === undefined || value === null) {\n      throw new Error(`Missing environment variable ${envVarName} required to build provider URL`);\n    }\n\n    return value;\n  });\n}\n\nfunction resolveApiKeyFromEnv(apiKeyEnvVar: ProviderConfig['apiKeyEnvVar']): string | undefined {\n  const envVars = Array.isArray(apiKeyEnvVar) ? apiKeyEnvVar : [apiKeyEnvVar];\n\n  for (const envVar of envVars) {\n    const apiKey = process.env[envVar];\n    if (apiKey) return apiKey;\n  }\n}\n\n// Provider-specific overrides for URL, npm package, and other config.\n// These take priority over what models.dev returns (e.g. correct base URLs, SDK packages).\n// This constant is ONLY used during generation in fetchProviders() to determine","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/gateways/models-dev.ts#L57-L93","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n// env: nothing set; template https://${AZURE_OPENAI_ENDPOINT}/openai/v1\n// after\nprocess.env.AZURE_OPENAI_ENDPOINT = 'my-resource.openai.azure.com';\n// or: new ModelsDevGateway({ envVars: { AZURE_OPENAI_ENDPOINT: 'my-resource.openai.azure.com' } })","handlingStrategy":"validation","validationCode":"const requiredVars = [...urlTemplate.matchAll(/\\$\\{([^}]+)\\}/g)].map(m => m[1].trim());\nconst missing = requiredVars.filter(k => !process.env[k]);\nif (missing.length) throw new Error(`Missing env vars for provider URL: ${missing.join(', ')}`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["environment","url","configuration","models-dev"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}