Invalid mount path: ${mountPath}. Must be an absolute path w

Error message

Invalid mount path: ${mountPath}. Must be an absolute path with alphanumeric, dash, dot, underscore, or slash characters only.

What it means

LocalSandbox validates every mount path against SAFE_MOUNT_PATH (`/^\/[a-zA-Z0-9_.\-/]+$/`) before mounting or unmounting. The path must be absolute and contain only safe characters — no spaces, backslashes, `~`, `:` (Windows drives), or URL-encoded segments. This prevents injection/escaping bugs in path handling.

Source

Thrown at packages/core/src/workspace/sandbox/local-sandbox.ts:63

/**
 * Directory for mount marker files used to detect config changes across restarts.
 *
 * Resolved lazily so `os.tmpdir()` is never invoked at module-load time. The
 * Agent/evals runtime (which transitively imports this module) is bundled into
 * the Studio client, where `node:os` is shimmed to an empty object and
 * `os.tmpdir` is `undefined`. Evaluating it at import time crashes Studio boot.
 * See https://github.com/mastra-ai/mastra/issues/18519.
 */
export function getMarkerDir(): string {
  return path.join(os.tmpdir(), '.mastra-mounts');
}

/** Allowlist pattern for mount paths — absolute path with safe characters only. */
const SAFE_MOUNT_PATH = /^\/[a-zA-Z0-9_.\-/]+$/;

function validateMountPath(mountPath: string): void {
  if (!SAFE_MOUNT_PATH.test(mountPath)) {
    throw new Error(
      `Invalid mount path: ${mountPath}. Must be an absolute path with alphanumeric, dash, dot, underscore, or slash characters only.`,
    );
  }
  const segments = mountPath.split('/').filter(Boolean);
  if (segments.length === 0) {
    throw new Error(`Invalid mount path: ${mountPath}. Root path "/" is not allowed.`);
  }
  if (segments.some(seg => seg === '.' || seg === '..')) {
    throw new Error(`Invalid mount path: ${mountPath}. Path segments cannot be "." or "..".`);
  }
}

/** Canonicalize mount path so `/data`, `/data/`, `//data` all resolve to `/data`. */
function normalizeMountPath(mountPath: string): string {
  return `/${mountPath.split('/').filter(Boolean).join('/')}`;
}

// =============================================================================

View on GitHub (pinned to 75dd419e61)

Solutions

Convert the path to an absolute POSIX-style path starting with `/`
Sanitize or reject paths containing characters outside [a-zA-Z0-9_.-/] before calling mount/unmount
Expand `~` and resolve relative paths yourself with `path.resolve` before passing them in

Example fix

// before
sandbox.mount('~/my data');
// after
import os from 'os';
import path from 'path';
const target = path.resolve(process.env.DATA_DIR ?? '/data');
if (!/^\/[a-zA-Z0-9_.\-/]+$/.test(target)) throw new Error(`Unsafe mount path: ${target}`);
sandbox.mount(target);

Defensive patterns

Strategy: validation

Validate before calling

const SAFE_MOUNT_PATH = /^\/[a-zA-Z0-9_.\-/]+$/;
export function assertSafeMountPath(p: string) {
  if (!SAFE_MOUNT_PATH.test(p)) throw new Error(`Invalid mount path: ${p}`);
}

Try / catch

try {
  await sandbox.mount(userPath);
} catch (err) {
  if (/Invalid mount path/.test(String(err?.message))) {
    throw new Error(`Configure an absolute POSIX mount path (e.g. /data); got: ${userPath}`);
  }
  throw err;
}

Prevention

Run path.resolve and reject non-POSIX (Windows/backslash) paths at config-load time
Expand ~ and env vars yourself; never pass raw user/environment strings to mount()
Add a schema (zod regex) to your config validation for mount paths

When it happens

Trigger: Calling `sandbox.mount(path)` or `sandbox.unmount(path)` with a relative path (`data`), a path with spaces (`/my data`), a Windows path (`C:\data`), a `~` shortcut, or any character outside [a-zA-Z0-9_.-/].

Common situations: Using user-supplied or env-derived paths without sanitizing; developing on Windows and passing `C:\...` paths; using `path.join` with relative segments; shell-style `~` expansion.

Related errors

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