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'.

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)

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;
}

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');

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 {
  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;
}

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

• Resource-limit preflight command failed.
• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" does not support exec
• Sandbox provider "${sandbox.provider}" does not support exec
• Sandbox provider "${options.sandbox.provider}" does not supp

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