mastra-ai/mastra · error

Could not resolve the sandbox home directory. Pass `remoteDi

Error message

Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.

What it means

resolveRemoteDir determines the remote upload directory by printing $HOME (falling back to pwd) inside the sandbox. If the sandbox returns empty output for that probe, the library cannot guess where to place files and throws, telling you to pass remoteDir explicitly.

Source

Thrown at deployers/sandbox/src/shared.ts:36

  try {
    return await sandbox.getInfo?.();
  } catch {
    return undefined;
  }
}

/**
 * Resolve the directory the app is (or will be) deployed into. Defaults to
 * `$HOME/mastra-app` resolved inside the sandbox — home directories persist
 * across snapshot stop/resume on providers that support it, unlike `/tmp`.
 * The sandbox must be running.
 */
export async function resolveRemoteDir(sandbox: WorkspaceSandbox, remoteDir?: string): Promise<string> {
  if (remoteDir) return remoteDir;
  const result = await runInSandbox(sandbox, `printf %s "\${HOME:-$(pwd)}"`, { allowFailure: true });
  const base = result.stdout.trim();
  if (!base) {
    throw new Error('Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.');
  }
  return `${base}/${REMOTE_DIR_NAME}`;
}

/** Single-quote a value for POSIX shells. */
export function shellQuote(value: string): string {
  return `'${value.replace(/'/g, `'\\''`)}'`;
}

/** Run a shell script string inside the sandbox and throw on failure. */
export async function runInSandbox(
  sandbox: WorkspaceSandbox,
  script: string,
  opts?: {
    allowFailure?: boolean;
    timeout?: number;
    /** Safe description used in error messages instead of the script itself. */
    label?: string;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass `remoteDir` explicitly in your deploy/upload options so no probe is needed.
2. Verify the sandbox provider actually returns stdout from executeCommand (test with a trivial `echo hi` command).
3. Use a sandbox image with a POSIX shell (sh) and a HOME or valid working directory.

Example fix

// before
await deployToSandbox({ sandbox });
// after
await deployToSandbox({ sandbox, remoteDir: '/home/user/.mastra-deploy' });

if (!options.remoteDir && !(await canProbeHome(sandbox))) throw new Error('Provide remoteDir: sandbox cannot resolve HOME');

try {
  await deployToSandbox({ sandbox });
} catch (e) {
  if (e.message.includes('sandbox home directory')) {
    await deployToSandbox({ sandbox, remoteDir: '/root/.mastra-deploy' });
  } else throw e;
}

When it happens

Trigger: Calling a sandbox deploy/upload without `remoteDir` while the sandbox's executeCommand returns empty stdout for `printf %s "${HOME:-$(pwd)}"` (allowFailure is set, so a failing command also yields empty stdout).

Common situations: Minimal or non-POSIX sandbox images without a shell HOME set; providers whose exec API swallows stdout; sandboxes where the default working directory is unavailable.

Related errors

• Sandbox provider "${sandbox.provider}" does not support exec
• Command failed inside sandbox (exit ${result.exitCode}): ${w
• Unknown worker resource limit: ${name}.
• MastraFactory: 'sandbox' is now a callback, not an options o
• MastraFactory: 'sandbox' must be a function constructing a M

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