{"record":{"id":"dd662a4d64ba3e1d","repo":"mastra-ai/mastra","slug":"could-not-resolve-the-sandbox-home-directory-pass","errorCode":null,"errorMessage":"Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.","messagePattern":"Could not resolve the sandbox home directory\\. Pass `remoteDir` explicitly\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/shared.ts","lineNumber":36,"sourceCode":"  try {\n    return await sandbox.getInfo?.();\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve the directory the app is (or will be) deployed into. Defaults to\n * `$HOME/mastra-app` resolved inside the sandbox — home directories persist\n * across snapshot stop/resume on providers that support it, unlike `/tmp`.\n * The sandbox must be running.\n */\nexport async function resolveRemoteDir(sandbox: WorkspaceSandbox, remoteDir?: string): Promise<string> {\n  if (remoteDir) return remoteDir;\n  const result = await runInSandbox(sandbox, `printf %s \"\\${HOME:-$(pwd)}\"`, { allowFailure: true });\n  const base = result.stdout.trim();\n  if (!base) {\n    throw new Error('Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.');\n  }\n  return `${base}/${REMOTE_DIR_NAME}`;\n}\n\n/** Single-quote a value for POSIX shells. */\nexport function shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\n/** Run a shell script string inside the sandbox and throw on failure. */\nexport async function runInSandbox(\n  sandbox: WorkspaceSandbox,\n  script: string,\n  opts?: {\n    allowFailure?: boolean;\n    timeout?: number;\n    /** Safe description used in error messages instead of the script itself. */\n    label?: string;","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/shared.ts#L18-L54","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass `remoteDir` explicitly in your deploy/upload options so no probe is needed.","Verify the sandbox provider actually returns stdout from executeCommand (test with a trivial `echo hi` command).","Use a sandbox image with a POSIX shell (sh) and a HOME or valid working directory."],"exampleFix":"// before\nawait deployToSandbox({ sandbox });\n// after\nawait deployToSandbox({ sandbox, remoteDir: '/home/user/.mastra-deploy' });","handlingStrategy":"try-catch","validationCode":"if (!options.remoteDir && !(await canProbeHome(sandbox))) throw new Error('Provide remoteDir: sandbox cannot resolve HOME');","typeGuard":null,"tryCatchPattern":"try {\n  await deployToSandbox({ sandbox });\n} catch (e) {\n  if (e.message.includes('sandbox home directory')) {\n    await deployToSandbox({ sandbox, remoteDir: '/root/.mastra-deploy' });\n  } else throw e;\n}","preventionTips":["Always set remoteDir explicitly in production deploys","Test that the provider's executeCommand returns non-empty stdout for `echo hi`","Use standard sandbox images with POSIX shell and HOME set"],"tags":["sandbox","deploy","configuration"],"backgroundTag":"sandbox-home-resolution-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}