LOCAL_STORAGE_PATH

LOCAL_STORAGE_PATH

Error message

LOCAL_STORAGE_PATH: Build contains a host-local storage URL: ${truncate(d.value, 80)} (${d.hint})

What it means

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.

Source

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

  if (metadata) {
    detections = metadata.localPaths;
  } else {
    try {
      const raw = await readFile(join(outputDir, LOCAL_PATHS_METADATA_FILE), 'utf-8');
      detections = JSON.parse(raw) as LocalStorageDetection[];
    } catch {
      return [];
    }
  }

  if (!Array.isArray(detections) || detections.length === 0) return [];

  const issues: PreflightIssue[] = [];

  for (const d of detections) {
    if (!d.guardedBy) {
      issues.push({
        code: 'LOCAL_STORAGE_PATH',
        severity: 'error',
        message: `Build contains a host-local storage URL: ${truncate(d.value, 80)} (${d.hint})`,
        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.`,
      });
      continue;
    }

    // Guards on vars the platform/runtime sets automatically (e.g.
    // MASTRA_STORAGE_URL on Mastra Cloud) are trusted the same way the
    // missing-env-var check trusts them — the guard is satisfied at runtime
    // even though the var never appears in a local env file.
    if (isPlatformProvidedEnvVar(d.guardedBy)) continue;

    // The literal is a dead fallback when the guarding env var is set in the
    // deploy environment. An empty value doesn't count: `process.env.X || 'file:...'`
    // still takes the fallback at runtime when X is blank.
    if (envVars[d.guardedBy]) continue;

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
new LibSQLStore({ url: 'file:./mastra.db' })
// after
new LibSQLStore({ url: process.env.MASTRA_STORAGE_URL! })

Defensive patterns

Strategy: validation

Validate before calling

// pre-deploy guard: no local storage literals in src
import { readFileSync, readdirSync } from 'node:fs';
function scan(dir: string): string[] {
  return readdirSync(dir, { withFileTypes: true }).flatMap(e => {
    const p = `${dir}/${e.name}`;
    if (e.isDirectory()) return e.name === 'node_modules' ? [] : scan(p);
    if (!p.endsWith('.ts')) return [];
    const src = readFileSync(p, 'utf-8');
    return /file:\.|localhost|127\.0\.0\.1/.test(src) && /Store|Storage|db|url/i.test(src) ? [p] : [];
  });
}
const hits = scan('src'); if (hits.length) throw new Error(`Local storage literals in: ${hits.join(', ')}`);

Type guard

function isHostedStorageUrl(v: string): boolean {
  return /^(libsql|https?):\/\//.test(v) && !/localhost|127\.|0\.0\.0\.0|\[::1\]/.test(v);
}

Prevention

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

When it happens

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

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

Related errors

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