{"record":{"id":"abd5489cdf781f9e","repo":"mastra-ai/mastra","slug":"sandbox-command","errorCode":"sandbox_command","errorMessage":"sandbox_command","messagePattern":"sandbox_command","errorType":"error_code","errorClass":"SandboxWorkerCapabilityError","httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/worker.ts","lineNumber":280,"sourceCode":"  (\n    ulimit -S \"$flag\" \"$value\" >/dev/null 2>&1 || exit 1\n    ulimit -H \"$flag\" \"$value\" >/dev/null 2>&1 || exit 1\n    [ \"$(ulimit -S \"$flag\")\" = \"$value\" ] || exit 1\n    [ \"$(ulimit -H \"$flag\")\" = \"$value\" ] || exit 1\n    if ulimit -H \"$flag\" \"$((value + 1))\" >/dev/null 2>&1; then exit 1; fi\n  ) || fail \"$capability\"\n}\n[ \"$(uname -s 2>/dev/null)\" = Linux ] && [ -r /proc/self/stat ] || fail linux_proc\ncommand -v setsid >/dev/null 2>&1 || fail process_groups\nsetsid sh -c 'kill -0 -$$ 2>/dev/null' || fail process_groups\n${checks.join('\\n')}\n`;\n\n  let result;\n  try {\n    result = await runInSandbox(sandbox, script, { allowFailure: true, label: 'preflight worker resource limits' });\n  } catch (error) {\n    throw new SandboxWorkerCapabilityError('sandbox_command', undefined, { cause: error });\n  }\n  if (result.exitCode === 0) return;\n\n  const detail = `${result.stderr}\\n${result.stdout}`;\n  const match = detail.match(new RegExp(`${RESOURCE_CAPABILITY_PREFIX}([a-z_]+)`));\n  const capability = (match?.[1] ?? 'sandbox_command') as SandboxWorkerResourceLimitCapability;\n  throw new SandboxWorkerCapabilityError(capability, undefined, {\n    cause: new Error(detail.trim() || 'Resource-limit preflight command failed.'),\n  });\n}\n\nasync function acquireLock(\n  sandbox: WorkspaceSandbox,\n  lock: string,\n  timeout: number | undefined,\n  label: string,\n): Promise<void> {\n  const timeoutMs = timeout ?? 600_000;","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/worker.ts#L262-L298","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect error.cause for the underlying runInSandbox failure (connection, auth, timeout) and fix that root cause.","Verify the sandbox is running and supports executeCommand; recreate/start the sandbox if it was destroyed or stopped.","Retry the deploy if the failure was transient (network blip); the preflight runs again on the next attempt.","If the provider genuinely cannot execute commands for preflight, deploy without resourceLimits or choose a provider that supports command execution."],"exampleFix":"// before\nconst deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { cpuTimeSeconds: 60 } });\n// after\nlet deployment;\ntry {\n  deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { cpuTimeSeconds: 60 } });\n} catch (error) {\n  if (error instanceof SandboxWorkerCapabilityError && error.code === 'sandbox_command') {\n    console.error('sandbox exec unavailable during preflight:', error.cause);\n  }\n  throw error;\n}","handlingStrategy":"try-catch","validationCode":"if (!sandbox.executeCommand) {\n  throw new Error('This sandbox provider does not support executeCommand; resourceLimits require it.');\n}\n// optionally smoke-test command execution before deploy:\nawait sandbox.executeCommand('echo ok');","typeGuard":"function isCapabilityError(error) {\n  return error instanceof Object && 'code' in error && typeof error.code === 'string';\n}\n// check specifically:\nfunction isSandboxCommandError(error) {\n  return isCapabilityError(error) && error.code === 'sandbox_command';\n}","tryCatchPattern":"try {\n  return await deployWorkerToSandbox(options);\n} catch (error) {\n  if (isCapabilityError(error) && error.code === 'sandbox_command') {\n    console.error('Sandbox exec failed during preflight; cause:', error.cause);\n    if (isTransient(error.cause)) return retryDeploy(options); // bounded retry\n  }\n  throw error;\n}","preventionTips":["Health-check the sandbox (executeCommand echo) immediately before deploying workers.","Refresh provider credentials before long deploy pipelines.","Confirm the sandbox status is running, not stopped/destroyed, before deploying.","Only request resourceLimits on providers verified to support command execution."],"tags":["sandbox","capability","resource-limits","preflight"],"backgroundTag":"sandbox-command-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}