mastra-ai/mastra · error · SandboxWorkerCapabilityError

sandbox_command

sandbox_command

Error message

sandbox_command

What it means

Before deploying a worker with resourceLimits, preflightResourceLimits runs a shell script in the sandbox that verifies the sandbox can actually enforce each requested ulimit (soft+hard set/verify, raising one step must fail) plus Linux prerequisites (/proc, setsid process groups). If the runInSandbox call itself throws (e.g. the provider cannot execute commands, sandbox stopped, command infrastructure broken), the error is rethrown as SandboxWorkerCapabilityError with code 'sandbox_command'.

Solutions

  1. Inspect error.cause for the underlying runInSandbox failure (connection, auth, timeout) and fix that root cause.
  2. Verify the sandbox is running and supports executeCommand; recreate/start the sandbox if it was destroyed or stopped.
  3. Retry the deploy if the failure was transient (network blip); the preflight runs again on the next attempt.
  4. If the provider genuinely cannot execute commands for preflight, deploy without resourceLimits or choose a provider that supports command execution.

Example fix

// before
const deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { cpuTimeSeconds: 60 } });
// after
let deployment;
try {
  deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { cpuTimeSeconds: 60 } });
} catch (error) {
  if (error instanceof SandboxWorkerCapabilityError && error.code === 'sandbox_command') {
    console.error('sandbox exec unavailable during preflight:', error.cause);
  }
  throw error;
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!sandbox.executeCommand) {
  throw new Error('This sandbox provider does not support executeCommand; resourceLimits require it.');
}
// optionally smoke-test command execution before deploy:
await sandbox.executeCommand('echo ok');

Type guard

function isCapabilityError(error) {
  return error instanceof Object && 'code' in error && typeof error.code === 'string';
}
// check specifically:
function isSandboxCommandError(error) {
  return isCapabilityError(error) && error.code === 'sandbox_command';
}

Try / catch

try {
  return await deployWorkerToSandbox(options);
} catch (error) {
  if (isCapabilityError(error) && error.code === 'sandbox_command') {
    console.error('Sandbox exec failed during preflight; cause:', error.cause);
    if (isTransient(error.cause)) return retryDeploy(options); // bounded retry
  }
  throw error;
}

Prevention

When it happens

Trigger: Calling deployWorkerToSandbox with resourceLimits set while sandbox.executeCommand throws or the sandbox connection fails mid-preflight; sandbox was destroyed/stopped so command execution raises; a provider-level transport error (network, auth, timeout) aborts the preflight script execution rather than returning a nonzero exit.

Common situations: Deploying to a sandbox whose instance was reclaimed between creation and deploy; expired cloud credentials causing the exec API call to throw; requesting resourceLimits against a sandbox flavor that cannot run the preflight; transient network partition during deploy.

Related errors

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

Appendix: source

Thrown at deployers/sandbox/src/worker.ts:280

  (
    ulimit -S "$flag" "$value" >/dev/null 2>&1 || exit 1
    ulimit -H "$flag" "$value" >/dev/null 2>&1 || exit 1
    [ "$(ulimit -S "$flag")" = "$value" ] || exit 1
    [ "$(ulimit -H "$flag")" = "$value" ] || exit 1
    if ulimit -H "$flag" "$((value + 1))" >/dev/null 2>&1; then exit 1; fi
  ) || fail "$capability"
}
[ "$(uname -s 2>/dev/null)" = Linux ] && [ -r /proc/self/stat ] || fail linux_proc
command -v setsid >/dev/null 2>&1 || fail process_groups
setsid sh -c 'kill -0 -$$ 2>/dev/null' || fail process_groups
${checks.join('\n')}
`;

  let result;
  try {
    result = await runInSandbox(sandbox, script, { allowFailure: true, label: 'preflight worker resource limits' });
  } catch (error) {
    throw new SandboxWorkerCapabilityError('sandbox_command', undefined, { cause: error });
  }
  if (result.exitCode === 0) return;

  const detail = `${result.stderr}\n${result.stdout}`;
  const match = detail.match(new RegExp(`${RESOURCE_CAPABILITY_PREFIX}([a-z_]+)`));
  const capability = (match?.[1] ?? 'sandbox_command') as SandboxWorkerResourceLimitCapability;
  throw new SandboxWorkerCapabilityError(capability, undefined, {
    cause: new Error(detail.trim() || 'Resource-limit preflight command failed.'),
  });
}

async function acquireLock(
  sandbox: WorkspaceSandbox,
  lock: string,
  timeout: number | undefined,
  label: string,
): Promise<void> {
  const timeoutMs = timeout ?? 600_000;

View on GitHub (pinned to 75dd419e61)