{"record":{"id":"2522868d438d22bb","repo":"mastra-ai/mastra","slug":"local-storage-path","errorCode":"LOCAL_STORAGE_PATH","errorMessage":"LOCAL_STORAGE_PATH: Build contains a host-local storage URL: ${truncate(d.value, 80)} (${d.hint})","messagePattern":"LOCAL_STORAGE_PATH: Build contains a host-local storage URL: (.+?) \\((.+?)\\)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/deploy-preflight.ts","lineNumber":557,"sourceCode":"  if (metadata) {\n    detections = metadata.localPaths;\n  } else {\n    try {\n      const raw = await readFile(join(outputDir, LOCAL_PATHS_METADATA_FILE), 'utf-8');\n      detections = JSON.parse(raw) as LocalStorageDetection[];\n    } catch {\n      return [];\n    }\n  }\n\n  if (!Array.isArray(detections) || detections.length === 0) return [];\n\n  const issues: PreflightIssue[] = [];\n\n  for (const d of detections) {\n    if (!d.guardedBy) {\n      issues.push({\n        code: 'LOCAL_STORAGE_PATH',\n        severity: 'error',\n        message: `Build contains a host-local storage URL: ${truncate(d.value, 80)} (${d.hint})`,\n        fix: `Replace it with a hosted URL (e.g. a Turso \\`libsql://...\\` URL or a public Postgres connection string) and store it in your env file.`,\n      });\n      continue;\n    }\n\n    // Guards on vars the platform/runtime sets automatically (e.g.\n    // MASTRA_STORAGE_URL on Mastra Cloud) are trusted the same way the\n    // missing-env-var check trusts them — the guard is satisfied at runtime\n    // even though the var never appears in a local env file.\n    if (isPlatformProvidedEnvVar(d.guardedBy)) continue;\n\n    // The literal is a dead fallback when the guarding env var is set in the\n    // deploy environment. An empty value doesn't count: `process.env.X || 'file:...'`\n    // still takes the fallback at runtime when X is blank.\n    if (envVars[d.guardedBy]) continue;\n","sourceCodeStart":539,"sourceCodeEnd":575,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/deploy-preflight.ts#L539-L575","documentation":"LOCAL_STORAGE_PATH (error variant) is emitted by `mastra deploy` preflight when the mastra-local-storage-detector Rollup plugin found a hardcoded host-local storage URL (e.g. `file:./mastra.db`, `postgres://localhost/...`) in the build output, and that literal is NOT guarded by any env var. The URL would be used verbatim on the deployed server, where the local file/host doesn't exist, so preflight hard-errors instead of warning.","triggerScenarios":"`mastra deploy` reads preflight-metadata.json (or legacy preflight-local-paths.json) containing a detection `d` with no `guardedBy` field — i.e. the bundler saw a local storage literal not wrapped in an env-var fallback.","commonSituations":"Hardcoding `new LibSQLStore({ url: 'file:./mastra.db' })` or `postgres://localhost` directly in mastra config; dev-only storage config committed without an env-var indirection; older build where the guard was refactored away.","solutions":["Replace the hardcoded literal with `process.env.YOUR_VAR` and put the hosted URL in your env file (e.g. a Turso `libsql://...` URL or public Postgres connection string)","If a managed DB is intended, provision one (`mastra env db create`) and read its injected var via process.env in the storage config","Rebuild so the detector re-runs and confirms the literal is gone"],"exampleFix":"// before\nnew LibSQLStore({ url: 'file:./mastra.db' })\n// after\nnew LibSQLStore({ url: process.env.MASTRA_STORAGE_URL! })","handlingStrategy":"validation","validationCode":"// pre-deploy guard: no local storage literals in src\nimport { readFileSync, readdirSync } from 'node:fs';\nfunction scan(dir: string): string[] {\n  return readdirSync(dir, { withFileTypes: true }).flatMap(e => {\n    const p = `${dir}/${e.name}`;\n    if (e.isDirectory()) return e.name === 'node_modules' ? [] : scan(p);\n    if (!p.endsWith('.ts')) return [];\n    const src = readFileSync(p, 'utf-8');\n    return /file:\\.|localhost|127\\.0\\.0\\.1/.test(src) && /Store|Storage|db|url/i.test(src) ? [p] : [];\n  });\n}\nconst hits = scan('src'); if (hits.length) throw new Error(`Local storage literals in: ${hits.join(', ')}`);","typeGuard":"function isHostedStorageUrl(v: string): boolean {\n  return /^(libsql|https?):\\/\\//.test(v) && !/localhost|127\\.|0\\.0\\.0\\.0|\\[::1\\]/.test(v);\n}","tryCatchPattern":null,"preventionTips":["Always read storage URLs from process.env instead of hardcoding file:/localhost literals","Add a lint/CI rule that fails on file: or localhost storage literals outside test files","Run `mastra build` and the deploy preflight locally before pushing; fix detector findings at build time","Never ship the dev SQLite file config to shared branches"],"tags":["deploy","storage","localhost","hardcoded-config","preflight"],"backgroundTag":"local-storage-url-in-production","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}