Sandbox provider "${sandbox.provider}" does not support exec

Error message

Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.

What it means

runInSandbox is the single choke point for all shell commands in a sandbox deploy. The WorkspaceSandbox contract makes executeCommand optional; if the provider did not implement it, no command can run and the library fails fast with the provider name in the message.

Source

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

/** 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;
  },
): Promise<{ stdout: string; stderr: string; exitCode: number }> {
  if (!sandbox.executeCommand) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`,
    );
  }
  // Run via `sh -c` (argv style): providers pass `command` straight to their
  // exec API as an executable, so a raw script string with spaces would fail.
  const result = await sandbox.executeCommand(
    'sh',
    ['-c', script],
    opts?.timeout ? { timeout: opts.timeout } : undefined,
  );
  if (!result.success && !opts?.allowFailure) {
    // Never echo the full script back: it can contain secrets (env values)
    // or entire base64 upload chunks. Use the label or a bounded excerpt.
    const what = opts?.label ?? truncate(script, 120);
    throw new Error(
      `Command failed inside sandbox (exit ${result.exitCode}): ${what}\n${truncate(result.stderr || result.stdout, 4_000)}`,
    );
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Switch to a sandbox provider that implements executeCommand (e.g. the official providers for your target runtime).
If the provider is custom, implement `executeCommand` on your WorkspaceSandbox (run via sh -c, return {stdout, stderr, success/exitCode}).
Use a non-sandbox deployer if the target truly cannot execute commands.

Example fix

// before
const sandbox: WorkspaceSandbox = { provider: 'my-legacy', id: 'sbx_1' };
// after
const sandbox: WorkspaceSandbox = { provider: 'my-legacy', id: 'sbx_1', executeCommand: async (cmd, opts) => { /* exec via provider API */ } };

Defensive patterns

Strategy: validation

Validate before calling

if (typeof sandbox.executeCommand !== 'function') throw new Error(`Provider ${sandbox.provider} cannot run sandbox deploys`);

Type guard

function supportsExec(s: WorkspaceSandbox): s is WorkspaceSandbox & Required<Pick<WorkspaceSandbox, 'executeCommand'>> {
  return typeof s.executeCommand === 'function';
}

Prevention

Type-check sandbox objects at construction: executeCommand must be a function
Never round-trip sandbox objects through JSON (functions are dropped)
Prefer first-party providers; pin provider package versions with the deployer

When it happens

Trigger: Calling deployToSandbox (or anything that routes through runInSandbox: markerCheck, uploadFile, killPreviousServer, launchServer) with a sandbox object whose `executeCommand` is undefined.

Common situations: Using a custom or legacy provider that only implements file ops; hand-rolled WorkspaceSandbox objects; version upgrades where a provider has not yet added executeCommand support.

Related errors

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