{"record":{"id":"4604a19e9cd01c52","repo":"mastra-ai/mastra","slug":"database-url-is-required-outside-local-development","errorCode":null,"errorMessage":"DATABASE_URL is required outside local development and tests.","messagePattern":"DATABASE_URL is required outside local development and tests\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"mastracode/web/src/mastra/index.ts","lineNumber":245,"sourceCode":"// Postgres (the paired PgVector rides the same database for recall search).\n// Unset (bare local dev) → libSQL on the same local file the SDK's default\n// storage resolution uses, running the FULL app surface (auth, intake,\n// audit, work-items, integrations) — no features silently off.\n//\n// `APP_DATABASE_URL` is the deprecated legacy name — still honored as a\n// fallback so existing checkouts keep working, but new setups should use\n// `DATABASE_URL` (matches the platform's managed env-var sync for attached\n// databases, so `mastra deploy` populates it automatically).\nconst databaseUrl = process.env.DATABASE_URL?.trim() || process.env.APP_DATABASE_URL?.trim() || undefined;\nif (process.env.APP_DATABASE_URL?.trim() && !process.env.DATABASE_URL?.trim()) {\n  console.warn(\n    '[mastracode-web] APP_DATABASE_URL is deprecated — rename it to DATABASE_URL. ' +\n      'The old name is honored as a fallback for now, but new deploys should use DATABASE_URL.',\n  );\n}\nconst localDevelopmentMode = process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test';\nif (!databaseUrl && !localDevelopmentMode) {\n  throw new Error('DATABASE_URL is required outside local development and tests.');\n}\n\nconst storage = databaseUrl\n  ? new PgFactoryStorage({\n      id: 'mastra-code-storage',\n      connectionString: databaseUrl,\n      retention: DEFAULT_RETENTION,\n    })\n  : new LibSQLFactoryStorage({\n      id: 'mastra-code-storage',\n      url: `file:${getDatabasePath()}`,\n      retention: DEFAULT_RETENTION,\n    });\nconst vector = databaseUrl ? new PgVector({ id: 'mastra-code-vectors', connectionString: databaseUrl }) : undefined;\n\n// Deployment-stable secret for OAuth/link `state` signing. Shared by the\n// factory's integration signer and the channel-account-link deep link so both\n// sign/verify with the same key: webhook secret first, then the WorkOS cookie","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/web/src/mastra/index.ts#L227-L263","documentation":"The mastracode web entry requires a Postgres connection string for storage in any environment that is not local development (NODE_ENV=development) or tests (NODE_ENV=test). Without DATABASE_URL (or the deprecated APP_DATABASE_URL fallback), the module cannot construct PgFactoryStorage and deliberately fails at startup instead of running with no persistent storage. Local dev falls back to a file-based LibSQL database.","triggerScenarios":"Starting the server (via `mastra dev`, `mastra build`/`mastra deploy` bundling this entry) with NODE_ENV set to something other than development or test, and with neither DATABASE_URL nor APP_DATABASE_URL defined in the environment.","commonSituations":"Deploying to staging/production and forgetting the DATABASE_URL secret; setting NODE_ENV=production while relying on local defaults; CI jobs running the built server outside test mode; a secrets manager that names the variable differently (e.g. POSTGRES_URL); the rename from APP_DATABASE_URL to DATABASE_URL leaving the old value unset.","solutions":["Set DATABASE_URL to the Postgres connection string in the deployment environment, e.g. DATABASE_URL=postgres://user:pass@host:5432/db.","If APP_DATABASE_URL is still set, rename it to DATABASE_URL — the old name is a deprecated fallback that will be removed.","For local-only runs, keep NODE_ENV as development or test so the file-based LibSQL fallback is used, or still set DATABASE_URL to a local Postgres.","Check the deploy platform's secret/variable configuration (dashboard, helm values, docker env) to confirm the variable is actually injected into the server process."],"exampleFix":"// before (deploy env)\nNODE_ENV=production\nAPP_DATABASE_URL= (unset)\n// after\nNODE_ENV=production\nDATABASE_URL=postgres://user:pass@db-host:5432/mastra","handlingStrategy":"validation","validationCode":"if (!process.env.DATABASE_URL && !['development','test'].includes(process.env.NODE_ENV ?? '')) {\n  throw new Error('DATABASE_URL must be set for non-development environments');\n}","typeGuard":"function hasDatabaseUrl(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { DATABASE_URL: string } {\n  return typeof env.DATABASE_URL === 'string' && env.DATABASE_URL.length > 0;\n}","tryCatchPattern":"try {\n  await startServer();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('DATABASE_URL is required')) {\n    console.error('Missing DATABASE_URL: set postgres://... connection string for this environment.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Add DATABASE_URL to your deploy platform's required-secrets checklist (helm, terraform, docker-compose).","Rename APP_DATABASE_URL to DATABASE_URL everywhere before the fallback is removed.","Run a startup preflight that asserts required env vars per environment (production/staging require DATABASE_URL).","Use NODE_ENV=development locally only when the file-based LibSQL fallback is intended."],"tags":["configuration","environment-variables","database","startup","postgres"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}