Sandbox '${sandbox.id}' cannot resolve its workdir: no execu

Error message

Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation

What it means

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.

Source

Thrown at mastracode/factory/src/sandbox/session-sandbox.ts:131

 * `entry.workdir` instead.
 */
export async function resolveSessionWorkdir(
  sessionId: string,
  sandbox: WorkspaceSandbox,
  repoFullName: string,
): Promise<string> {
  const entry = sessionSandboxes.get(sessionId);
  if (entry?.workdir && entry.sandbox === sandbox) return entry.workdir;
  const workdir =
    deriveLocalWorkdir(sandbox, repoFullName) ?? remoteWorkdirFromHome(await probeHome(sandbox), repoFullName);
  if (entry && entry.sandbox === sandbox) entry.workdir = workdir;
  return workdir;
}

/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */
async function probeHome(sandbox: WorkspaceSandbox): Promise<string> {
  if (!sandbox.executeCommand) {
    throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);
  }
  const probe = await sandbox.executeCommand('pwd');
  const home = probe.stdout.trim().split('\n').pop()?.trim() ?? '';
  if (probe.exitCode !== 0 || !home.startsWith('/')) {
    throw new Error(
      `Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${
        probe.stderr.trim() || probe.stdout.trim() || 'empty output'
      }`,
    );
  }
  return home;
}

/**
 * The session's memoized sandbox (and its workdir) when one was already
 * constructed in this process, else undefined. Never constructs — passive
 * read paths use this so browsing files cannot provision a VM.
 */

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const dir = await sessionSandbox.workdir; // provider lacks executeCommand -> throws
// after
const sandbox = createSandbox({ provider: 'docker' }); // executable provider
const dir = await sessionSandbox.workdir;

Defensive patterns

Strategy: try-catch

Validate before calling

if (typeof sandbox.executeCommand !== 'function') {
  throw new Error(`Sandbox '${sandbox.id}' needs an executeCommand provider before resolving workdir`);
}

Type guard

function canResolveWorkdir(s: WorkspaceSandbox): boolean {
  return typeof s.executeCommand === 'function';
}

Try / catch

let workdir: string;
try {
  workdir = await session.sandbox.workdir;
} catch (e) {
  if (/cannot resolve its workdir|cwd probe failed/.test(e.message)) {
    workdir = fallbackWorkdir(session); // e.g. configured mount path
  } else {
    throw e;
  }
}

Prevention

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.

When it happens

Trigger: 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 '/'.

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

Related errors

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