mastra-ai/mastra · error · SandboxWorkerCapabilityError

Resource-limit preflight command failed.

Error message

Resource-limit preflight command failed.

What it means

When the resource-limit preflight script exits nonzero but its output does not contain a MASTRA_WORKER_CAPABILITY:<name> marker, preflightResourceLimits throws SandboxWorkerCapabilityError with a generic cause message 'Resource-limit preflight command failed.' (or the captured stderr/stdout detail). This covers unmarkable failures such as shell errors, missing binaries, or truncated output — the library knows limits can't be verified but not which capability is missing.

Source

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

}
[ "$(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;
  const attempts = Math.max(1, Math.ceil(timeoutMs / 1000));
  await runInSandbox(
    sandbox,
    [
      'i=0',
      `while ! mkdir ${shellQuote(lock)} 2>/dev/null; do`,
      `  if [ "$i" -ge ${attempts} ]; then echo ${shellQuote(`${label} lock timeout`)} >&2; exit 1; fi`,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read error.cause.message — it contains the raw stderr/stdout detail; use it to identify the real sandbox-side failure.
2. Re-run the deploy with debug logging of sandbox command output to see why the script exited nonzero without a marker.
3. Test the sandbox provider with a trivial executeCommand call; if basic commands fail, fix the sandbox image/runtime first.
4. As a workaround, deploy without resourceLimits, or choose a sandbox provider whose exec preserves stdout/stderr.

Example fix

// before
const deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { openFiles: 256 } });
// after
let deployment;
try {
  deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { openFiles: 256 } });
} catch (error) {
  if (error instanceof SandboxWorkerCapabilityError) {
    console.error('preflight detail:', error.cause?.message); // raw stderr/stdout from the sandbox
  }
  throw error;
}

// Verify basic shell behavior in the sandbox before requesting resource limits:
const probe = await sandbox.executeCommand('sh -c "uname -s; ls /proc/self/stat; command -v setsid"');
if (probe.exitCode !== 0) {
  throw new Error('Sandbox shell cannot run preflight; do not request resourceLimits on this provider.');
}

function isCapabilityError(error) {
  return error instanceof Object && 'code' in error && typeof error.code === 'string';
}
function hasDiagnosticCause(error) {
  return error instanceof Object && 'cause' in error && error.cause instanceof Error;
}

try {
  return await deployWorkerToSandbox(options);
} catch (error) {
  if (isCapabilityError(error) && hasDiagnosticCause(error)) {
    console.error('Preflight failed without a capability marker. Raw detail:', error.cause.message);
    // Option: fall back to deploying without resourceLimits
    const { resourceLimits, ...rest } = options;
    if (resourceLimits) return deployWorkerToSandbox(rest);
  }
  throw error;
}

When it happens

Trigger: The preflight script exits nonzero without printing the capability marker — e.g. /bin/sh unavailable or crashing, the script being killed by the sandbox before writing to stderr/stdout, output stripped by the provider, or the marker regex MASTRA_WORKER_CAPABILITY:([a-z_]+) not matching due to output sanitization.

Common situations: Minimal or hardened sandbox images (no sh builtins expected by the script); sandbox killing long commands; providers that swallow or rewrite stderr so the marker line is lost; running against non-Linux or restricted containers where uname//proc checks behave unexpectedly and output is mangled.

Related errors

• sandbox_command
• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" does not support exec
• Invalid environment variable name: "${key}"
• Sandbox provider "${sandbox.provider}" does not support exec

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