mastra-ai/mastra · error

Sandbox '${sandbox.id}' cannot run the session setup: no exe

Error message

Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation

What it means

runGuardedSetup() executes per-session sandbox setup commands, which require the sandbox to support command execution. If sandbox.executeCommand is undefined (an offline/passive or unimplemented sandbox adapter), the library refuses to run setup rather than silently skipping it. It is thrown while the session-setup hook runs inside start().

Source

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

async function writeMarker(sandbox: WorkspaceSandbox): Promise<void> {
  // Best-effort: a missing marker only re-runs the idempotent setup later.
  const marker = markerShellPath(sandbox);
  await sandbox.executeCommand!(`mkdir -p "$(dirname "${marker}")" && touch "${marker}"`).catch(() => {});
}

/**
 * Run the session setup, marker-guarded: skip when the marker exists (unless
 * the VM is known-fresh), otherwise run and write the marker only on
 * success. Setup failures propagate — no marker is written, so the next
 * attempt re-runs.
 */
async function runGuardedSetup(
  sandbox: WorkspaceSandbox,
  run: SessionSetupRun,
  { skipMarkerProbe, sessionId, repoFullName }: { skipMarkerProbe: boolean; sessionId: string; repoFullName: string },
): Promise<void> {
  if (!sandbox.executeCommand) {
    throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);
  }
  // Resolved from the live instance (the hook runs inside `start()`, so the
  // VM is up) and memoized on the session entry for passive readers.
  const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);
  if (!skipMarkerProbe && (await markerPresent(sandbox, workdir))) return;
  await run(sandbox, workdir);
  await writeMarker(sandbox);
}

/**
 * Build the session setup hook, which factory attaches to the constructed
 * sandbox with `setOnStart`. Runs inside the sandbox start
 * lifecycle: a fresh VM (`outcome: 'created'`) runs setup with no probe; a
 * reconnect probes the marker first, which re-runs setup after a failed or
 * crash-interrupted attempt. Throwing fails `start()` loudly — core treats
 * onStart errors as fatal.
 */
export function createSessionSetupHook(

View on GitHub (pinned to 75dd419e61)

Solutions

1. Implement executeCommand on your WorkspaceSandbox adapter so it can exec commands in the workspace.
2. Use a sandbox implementation that supports command execution (e.g. a local or VM-backed sandbox) for sessions that need setup.
3. Skip setup-requiring flows for passive sandboxes instead of starting a session setup hook.
4. If executeCommand is optional in your build, add an explicit capability check before constructing the session sandbox.

Example fix

// before
const sandbox: WorkspaceSandbox = { id: 'my-box' }; // no executeCommand
await startSession(sessionId, sandbox);

// after
const sandbox = await createLocalSandbox({ id: 'my-box' }); // provides executeCommand
if (!sandbox.executeCommand) throw new Error('Session sandbox requires executeCommand support');
await startSession(sessionId, sandbox);

// before starting a session that runs setup
if (typeof (sandbox as WorkspaceSandbox).executeCommand !== 'function') {
  throw new Error(`Sandbox ${sandbox.id} cannot run session setup; use a command-capable sandbox`);
}

function supportsCommands(sandbox: WorkspaceSandbox): sandbox is WorkspaceSandbox & { executeCommand: NonNullable<WorkspaceSandbox['executeCommand']> } {
  return typeof sandbox.executeCommand === 'function';
}

try {
  await startSession(sessionId, sandbox);
} catch (err) {
  if (err instanceof Error && err.message.includes('no executeCommand implementation')) {
    console.error(`Sandbox '${sandbox.id}' is passive; provision a command-capable sandbox for this flow`);
  } else throw err;
}

When it happens

Trigger: Passing a WorkspaceSandbox implementation without an executeCommand method (e.g. a read-only or stub sandbox) to a flow that triggers createSessionSetupHook, so the guarded setup cannot execute any commands.

Common situations: Using a local/browse-only sandbox adapter where command execution was intentionally omitted; a custom sandbox implementation missing the executeCommand method; a provider SDK integration that never wired up command execution; refactors that made executeCommand optional in the type.

Related errors

• ${this.constructor.name} implements neither start() nor the
• connect({ id, name }): "name" is required when connecting wi
• MemoryThread.${methodName}() requires an agentId. Pass it vi
• execa is not available in Cloudflare Workers
• Sandbox provider "${sandbox.provider}" does not support netw

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