MISSING_ENV_VAR

MISSING_ENV_VAR

Error message

MISSING_ENV_VAR: Build references ${name} but the env file being deployed does not provide it.

What it means

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.

Source

Thrown at packages/cli/src/commands/deploy-preflight.ts:439

    if (managed.has(name)) continue;
    if (isPlatformProvidedEnvVar(name)) continue;
    missing.push(name);
  }

  if (missing.length === 0) return issues;

  missing.sort();

  // Split provider-known env vars into their own MISSING_ENV_VAR issues so we
  // can attach an autofix hint (`create-managed-database`) — the deploy command
  // then offers inline provisioning. Everything else stays in the single
  // aggregated text warning.
  const unprovisioned: string[] = [];
  for (const name of missing) {
    const autofix = dbAutofixFor(name);
    if (autofix) {
      issues.push({
        code: 'MISSING_ENV_VAR',
        severity: 'warning',
        message: `Build references ${name} but the env file being deployed does not provide it.`,
        fix: `Add ${name} to your env file, or let \`mastra deploy\` provision a managed ${autofix.provider} for this environment.`,
        autofix,
      });
    } else {
      unprovisioned.push(name);
    }
  }

  if (unprovisioned.length > 0) {
    issues.push({
      code: 'MISSING_ENV_VAR',
      severity: 'warning',
      message: `Build references ${unprovisioned.length} env var(s) not in the env file being deployed: ${unprovisioned.join(', ')}`,
      fix: `Add them to your env file, or confirm your code provides a fallback (e.g. \`process.env.X ?? 'default'\`).`,
    });
  }

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before: .env has no DB var
// after:
DATABASE_URL=libsql://my-db.turso.io?authToken=...

Defensive patterns

Strategy: validation

Validate before calling

const required = ['DATABASE_URL']; // vars your build references
const envFile = parseDotenv(readFileSync('.env', 'utf-8'));
const missing = required.filter(name => !envFile[name]);
if (missing.length) throw new Error(`Missing env vars: ${missing.join(', ')}`);

Type guard

function hasEnvVars<T extends readonly string[]>(names: T, env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & Record<T[number], string> {
  return names.every(n => typeof env[n] === 'string' && env[n].length > 0);
}

Prevention

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

When it happens

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

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

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