{"record":{"id":"9030000e78c1fae3","repo":"mastra-ai/mastra","slug":"missing-env-var","errorCode":"MISSING_ENV_VAR","errorMessage":"MISSING_ENV_VAR: Build references ${name} but the env file being deployed does not provide it.","messagePattern":"MISSING_ENV_VAR: Build references (.+?) but the env file being deployed does not provide it\\.","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/cli/src/commands/deploy-preflight.ts","lineNumber":439,"sourceCode":"    if (managed.has(name)) continue;\n    if (isPlatformProvidedEnvVar(name)) continue;\n    missing.push(name);\n  }\n\n  if (missing.length === 0) return issues;\n\n  missing.sort();\n\n  // Split provider-known env vars into their own MISSING_ENV_VAR issues so we\n  // can attach an autofix hint (`create-managed-database`) — the deploy command\n  // then offers inline provisioning. Everything else stays in the single\n  // aggregated text warning.\n  const unprovisioned: string[] = [];\n  for (const name of missing) {\n    const autofix = dbAutofixFor(name);\n    if (autofix) {\n      issues.push({\n        code: 'MISSING_ENV_VAR',\n        severity: 'warning',\n        message: `Build references ${name} but the env file being deployed does not provide it.`,\n        fix: `Add ${name} to your env file, or let \\`mastra deploy\\` provision a managed ${autofix.provider} for this environment.`,\n        autofix,\n      });\n    } else {\n      unprovisioned.push(name);\n    }\n  }\n\n  if (unprovisioned.length > 0) {\n    issues.push({\n      code: 'MISSING_ENV_VAR',\n      severity: 'warning',\n      message: `Build references ${unprovisioned.length} env var(s) not in the env file being deployed: ${unprovisioned.join(', ')}`,\n      fix: `Add them to your env file, or confirm your code provides a fallback (e.g. \\`process.env.X ?? 'default'\\`).`,\n    });\n  }","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/deploy-preflight.ts#L421-L457","documentation":"MISSING_ENV_VAR (per-var variant) is a warning from `mastra deploy` preflight: the built code references a database env var Mastra recognizes (mapped to a known provider via dbAutofixFor), but the env file being deployed does not define it and no managed database injects it. This variant exists specifically so the CLI can attach a structured autofix (`create-managed-database`) and offer inline provisioning during deploy.","triggerScenarios":"Running `mastra deploy` when a provider-known DB env var (e.g. DATABASE_URL, TURSO_DATABASE_URL, POSTGRES_URL) is referenced by the build but: absent from the env file, not in managedEnvVarNames, and not flagged as platform-provided (isPlatformProvidedEnvVar).","commonSituations":"Deploying without a .env file; creating a fresh staging/production environment whose env file only has app secrets and no DB URL; switching storage providers and renaming the env var; CI deploying with an env file that omits the database config.","solutions":["Add the referenced DB var to the env file being deployed","Run `mastra env db create <environment> --kind <provider>` or accept the deploy prompt to provision a managed database (sets the var automatically)","Check `mastra env` / platform dashboard that the correct environment's stored vars actually contain the var"],"exampleFix":"// before: .env has no DB var\n// after:\nDATABASE_URL=libsql://my-db.turso.io?authToken=...","handlingStrategy":"validation","validationCode":"const required = ['DATABASE_URL']; // vars your build references\nconst envFile = parseDotenv(readFileSync('.env', 'utf-8'));\nconst missing = required.filter(name => !envFile[name]);\nif (missing.length) throw new Error(`Missing env vars: ${missing.join(', ')}`);","typeGuard":"function hasEnvVars<T extends readonly string[]>(names: T, env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & Record<T[number], string> {\n  return names.every(n => typeof env[n] === 'string' && env[n].length > 0);\n}","tryCatchPattern":null,"preventionTips":["Commit a .env.example listing all required vars and validate real env files against it in CI","Provision managed DBs via `mastra env db create` instead of relying on env files","Fail fast at app boot with an explicit check for required DB env vars"],"tags":["deploy","env-var","database","missing-config","preflight"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}