mastra-ai/mastra · error

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

deployToSandbox requires the provider to support executeCommand to run install/start commands inside the sandbox. After the networking check passes, the engine verifies sandbox.executeCommand exists; a provider without it cannot deploy.

Source

Thrown at deployers/sandbox/src/engine.ts:74

    logger = noopLogger,
  } = options;

  if (!existsSync(join(dir, 'index.mjs'))) {
    throw new Error(`No index.mjs found in "${dir}" — did the build succeed?`);
  }

  // 1. Start (providers handle create-or-resume by identity, e.g. sandbox name).
  logger.info(`Starting ${sandbox.provider} sandbox...`);
  await sandbox.start?.();

  if (!supportsNetworking(sandbox)) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support networking (public port URLs), ` +
        `which is required for sandbox deploys.`,
    );
  }
  if (!sandbox.executeCommand) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`,
    );
  }

  const url = await sandbox.networking.getPortUrl(port);
  if (!url) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" did not expose a public URL for port ${port}. ` +
        `Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`,
    );
  }

  // Default the remote dir to $HOME/mastra-app — home directories persist
  // across snapshot stop/resume (unlike /tmp), so wakes find the app intact.
  const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);

  const mergedEnv = { ...env };
  if (studio && mergedEnv.MASTRA_STUDIO_PATH === undefined) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a provider implementation that supports executeCommand
2. Implement executeCommand(cmd, opts) in a custom provider (run a shell command inside the sandbox)
3. Double-check you are passing a Sandbox instance, not a client or config object

Example fix

// before
await deployToSandbox(urlProxySandbox, opts); // no executeCommand
// after
await deployToSandbox(fullCloudSandbox, opts); // implements executeCommand

if (typeof sandbox.executeCommand !== 'function') {
  console.warn('provider cannot run commands; sandbox deploys require executeCommand');
}

function supportsExecuteCommand(s: Sandbox): s is Sandbox & Required<Pick<Sandbox, 'executeCommand'>> {
  return typeof (s as any).executeCommand === 'function';
}

When it happens

Trigger: deployToSandbox is called with a sandbox object whose executeCommand method is undefined — feature check `if (!sandbox.executeCommand)` fires.

Common situations: Custom or mock sandbox implementations missing executeCommand; providers that only support start/stop (e.g. pure URL proxies); passing the wrong object type as the first argument.

Related errors

• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" did not expose a publ
• Woke sandbox but the Mastra server did not become healthy at
• No index.mjs found in "${dir}" — did the build succeed?
• Sandbox provider "${sandbox.provider}" did not expose a publ

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