{"record":{"id":"812fc9ca15ca7399","repo":"mastra-ai/mastra","slug":"localhost-env-var","errorCode":"LOCALHOST_ENV_VAR","errorMessage":"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.","messagePattern":"LOCALHOST_ENV_VAR: (.+?) in the env file being deployed points at localhost \\((.+?)\\) — the deployed server won't be able to reach it\\.","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/cli/src/commands/deploy-preflight.ts","lineNumber":410,"sourceCode":"  managedEnvVarNames?: string[] | null,\n): PreflightIssue[] {\n  const provided = new Set(Object.keys(envVars));\n  const managed = new Set(managedEnvVarNames ?? []);\n  const missing: string[] = [];\n  const issues: PreflightIssue[] = [];\n\n  for (const name of new Set(referenced)) {\n    if (provided.has(name)) {\n      // Present but pointing at the local machine: the value works in dev\n      // but can't be reached from the deployed server. Only flagged for\n      // provider-known vars (where we can offer a managed replacement) and\n      // only when no managed database already injects the var at deploy\n      // time (managed values win the platform's env merge, so a localhost\n      // value in the env file is then harmless).\n      const autofix = dbAutofixFor(name);\n      if (autofix && !managed.has(name) && isLocalhostUrl(envVars[name]!)) {\n        issues.push({\n          code: 'LOCALHOST_ENV_VAR',\n          severity: 'warning',\n          // Only the host is echoed — connection URLs can carry credentials,\n          // and preflight warnings end up in CI logs.\n          message: `${name} in the env file being deployed points at localhost (${localhostHostOf(envVars[name]!)}) — the deployed server won't be able to reach it.`,\n          fix: `Point ${name} at a hosted ${autofix.provider} instance, or let \\`mastra deploy\\` provision a managed ${autofix.provider} for this environment.`,\n          autofix,\n        });\n      }\n      continue;\n    }\n    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();","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/deploy-preflight.ts#L392-L428","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Replace the var's value with a hosted instance URL (hosted Postgres, Turso libsql://, etc.) in the env file being deployed","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","Ignore only if a managed database is later attached — managed env values win the platform env merge, making the localhost value harmless"],"exampleFix":"// .env (before)\nDATABASE_URL=postgresql://localhost:5432/mastra\n// .env (after)\nDATABASE_URL=postgresql://user:pass@db.internal.example.com:5432/mastra","handlingStrategy":"validation","validationCode":"function isLocalhostUrl(value: string): boolean {\n  try {\n    const host = new URL(value).hostname.replace(/^\\[|\\]$/g, '');\n  } catch { return false; }\n  return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '0.0.0.0' || host.startsWith('127.');\n}\n// before deploy:\nfor (const [k, v] of Object.entries(parsedEnv)) {\n  if (/DB|DATABASE|POSTGRES|TURSO|LIBSQL/i.test(k) && v && isLocalhostUrl(v)) console.warn(`${k} points at localhost`);\n}","typeGuard":"function isHostedDbUrl(v: string | undefined): v is string {\n  if (!v) return false;\n  try {\n    const h = new URL(v).hostname.replace(/^\\[|\\]$/g, '');\n    return !(h === 'localhost' || h.endsWith('.localhost') || h === '::1' || h === '0.0.0.0' || h.startsWith('127.'));\n  } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Keep separate dev (.env.development) and deploy (.env.production) env files; never deploy the dev one","Run the preflight check / `mastra deploy` dry validation in CI before real deploys","Use a hosted database even for shared/preview environments","Let mastra provision managed databases so localhost values can't leak into deploys"],"tags":["deploy","env-var","localhost","database","preflight"],"backgroundTag":"localhost-env-var-in-deployment","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}