{"record":{"id":"dd2940e60c8790a4","repo":"mastra-ai/mastra","slug":"sandbox-sandbox-id-cannot-resolve-its-workdir","errorCode":null,"errorMessage":"Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation","messagePattern":"Sandbox '(.+?)' cannot resolve its workdir: no executeCommand implementation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"mastracode/factory/src/sandbox/session-sandbox.ts","lineNumber":131,"sourceCode":" * `entry.workdir` instead.\n */\nexport async function resolveSessionWorkdir(\n  sessionId: string,\n  sandbox: WorkspaceSandbox,\n  repoFullName: string,\n): Promise<string> {\n  const entry = sessionSandboxes.get(sessionId);\n  if (entry?.workdir && entry.sandbox === sandbox) return entry.workdir;\n  const workdir =\n    deriveLocalWorkdir(sandbox, repoFullName) ?? remoteWorkdirFromHome(await probeHome(sandbox), repoFullName);\n  if (entry && entry.sandbox === sandbox) entry.workdir = workdir;\n  return workdir;\n}\n\n/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */\nasync function probeHome(sandbox: WorkspaceSandbox): Promise<string> {\n  if (!sandbox.executeCommand) {\n    throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);\n  }\n  const probe = await sandbox.executeCommand('pwd');\n  const home = probe.stdout.trim().split('\\n').pop()?.trim() ?? '';\n  if (probe.exitCode !== 0 || !home.startsWith('/')) {\n    throw new Error(\n      `Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${\n        probe.stderr.trim() || probe.stdout.trim() || 'empty output'\n      }`,\n    );\n  }\n  return home;\n}\n\n/**\n * The session's memoized sandbox (and its workdir) when one was already\n * constructed in this process, else undefined. Never constructs — passive\n * read paths use this so browsing files cannot provision a VM.\n */","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/sandbox/session-sandbox.ts#L113-L149","documentation":"probeHome resolves a session's working directory by running `pwd` in the sandbox's default shell cwd (its home dir). If the sandbox has no executeCommand implementation it cannot run the probe at all, so workdir throws this error instead of returning a bogus path; a related error covers probes that run but exit non-zero or return a non-absolute path.","triggerScenarios":"Accessing the session sandbox's workdir (which lazily calls probeHome) when sandbox.executeCommand is undefined — the same class of misconfiguration as error 508 but surfaced at workdir resolution; also when `pwd` exits non-zero or its last stdout line does not start with '/'.","commonSituations":"Non-executing sandbox providers (preview/read-only modes) used where a shell is required; custom sandbox implementations missing executeCommand; a VM whose default shell lands in a deleted or non-absolute cwd making the probe fail.","solutions":["Switch to a sandbox provider that implements executeCommand so the pwd probe can run.","Implement executeCommand in your custom provider, ensuring `pwd` works in the default shell and returns an absolute path.","Verify the sandbox image/VM's default shell starts in a valid home directory (HOME set, directory exists).","Ensure executeCommand returns the shape the library expects ({ stdout, stderr, exitCode }) so probe results parse correctly."],"exampleFix":"// before\nconst dir = await sessionSandbox.workdir; // provider lacks executeCommand -> throws\n// after\nconst sandbox = createSandbox({ provider: 'docker' }); // executable provider\nconst dir = await sessionSandbox.workdir;","handlingStrategy":"try-catch","validationCode":"if (typeof sandbox.executeCommand !== 'function') {\n  throw new Error(`Sandbox '${sandbox.id}' needs an executeCommand provider before resolving workdir`);\n}","typeGuard":"function canResolveWorkdir(s: WorkspaceSandbox): boolean {\n  return typeof s.executeCommand === 'function';\n}","tryCatchPattern":"let workdir: string;\ntry {\n  workdir = await session.sandbox.workdir;\n} catch (e) {\n  if (/cannot resolve its workdir|cwd probe failed/.test(e.message)) {\n    workdir = fallbackWorkdir(session); // e.g. configured mount path\n  } else {\n    throw e;\n  }\n}","preventionTips":["Check executeCommand exists before first workdir access.","Ensure the sandbox image has a valid HOME and default shell cwd.","Smoke-test the provider with a `pwd` command at session startup.","Return { stdout, stderr, exitCode } correctly from custom executeCommand implementations."],"tags":["sandbox","workdir","missing-capability"],"backgroundTag":"sandbox-provider-missing-execute","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}