mastra-ai/mastra · warning

LOCALHOST_ENV_VAR

LOCALHOST_ENV_VAR

Error message

LOCALHOST_ENV_VAR: ${name} in the env file being deployed points at localhost (${localhostHostOf(envVars[name]!)}) — the deployed server won't be able to reach it.

What it means

LOCALHOST_ENV_VAR is a warning emitted by the `mastra deploy` preflight check (checkEnvVarNames in packages/cli/src/commands/deploy-preflight.ts). It fires when an env var the build references is present in the env file being deployed, but its value is a localhost/127.0.0.1/::1 URL for a database provider Mastra knows about. Such a value works in local dev but the deployed server cannot reach your machine, so it would fail at runtime.

Source

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

  managedEnvVarNames?: string[] | null,
): PreflightIssue[] {
  const provided = new Set(Object.keys(envVars));
  const managed = new Set(managedEnvVarNames ?? []);
  const missing: string[] = [];
  const issues: PreflightIssue[] = [];

  for (const name of new Set(referenced)) {
    if (provided.has(name)) {
      // Present but pointing at the local machine: the value works in dev
      // but can't be reached from the deployed server. Only flagged for
      // provider-known vars (where we can offer a managed replacement) and
      // only when no managed database already injects the var at deploy
      // time (managed values win the platform's env merge, so a localhost
      // value in the env file is then harmless).
      const autofix = dbAutofixFor(name);
      if (autofix && !managed.has(name) && isLocalhostUrl(envVars[name]!)) {
        issues.push({
          code: 'LOCALHOST_ENV_VAR',
          severity: 'warning',
          // Only the host is echoed — connection URLs can carry credentials,
          // and preflight warnings end up in CI logs.
          message: `${name} in the env file being deployed points at localhost (${localhostHostOf(envVars[name]!)}) — the deployed server won't be able to reach it.`,
          fix: `Point ${name} at a hosted ${autofix.provider} instance, or let \`mastra deploy\` provision a managed ${autofix.provider} for this environment.`,
          autofix,
        });
      }
      continue;
    }
    if (managed.has(name)) continue;
    if (isPlatformProvidedEnvVar(name)) continue;
    missing.push(name);
  }

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

  missing.sort();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Replace the var's value with a hosted instance URL (hosted Postgres, Turso libsql://, etc.) in the env file being deployed
2. Run `mastra env db create <environment> --kind <provider>` (or accept the inline deploy autofix) to let mastra provision a managed database; managed values override the env file at deploy time
3. Ignore only if a managed database is later attached — managed env values win the platform env merge, making the localhost value harmless

Example fix

// .env (before)
DATABASE_URL=postgresql://localhost:5432/mastra
// .env (after)
DATABASE_URL=postgresql://user:pass@db.internal.example.com:5432/mastra

function isLocalhostUrl(value: string): boolean {
  try {
    const host = new URL(value).hostname.replace(/^\[|\]$/g, '');
  } catch { return false; }
  return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '0.0.0.0' || host.startsWith('127.');
}
// before deploy:
for (const [k, v] of Object.entries(parsedEnv)) {
  if (/DB|DATABASE|POSTGRES|TURSO|LIBSQL/i.test(k) && v && isLocalhostUrl(v)) console.warn(`${k} points at localhost`);
}

function isHostedDbUrl(v: string | undefined): v is string {
  if (!v) return false;
  try {
    const h = new URL(v).hostname.replace(/^\[|\]$/g, '');
    return !(h === 'localhost' || h.endsWith('.localhost') || h === '::1' || h === '0.0.0.0' || h.startsWith('127.'));
  } catch { return false; }
}

When it happens

Trigger: Running `mastra deploy` when: a provider-known DB var (e.g. DATABASE_URL / LIBSQL_URL / POSTGRES_URL per DB_ENV_VAR_NAMES) is set in the env file; the value parses as a URL whose host is localhost, *.localhost, 127.*, 0.0.0.0, or ::1 (isLocalhostUrl); and no managed database already injects that var (name not in managedEnvVarNames).

Common situations: Developer prototypes against a local Postgres/Turso/SQLite file (`postgresql://localhost:5432/mydb`, `file:./mastra.db`) and deploys the same .env to staging/production; copying the dev .env into CI; forgetting to swap in a hosted connection string before deploy.

Related errors

• MISSING_ENV_VAR
• LOCAL_STORAGE_PATH
• MastraAuthBetterAuth needs a database to build its own bette
• Clerk JWKS URI, secret key and publishable key are required,
• Google client ID is required. Provide it in the options or s

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/812fc9ca15ca7399. Report an issue: GitHub.