{"record":{"id":"da7f029ae38d8ad0","repo":"mastra-ai/mastra","slug":"resource-limit-preflight-command-failed","errorCode":null,"errorMessage":"Resource-limit preflight command failed.","messagePattern":"Resource-limit preflight command failed\\.","errorType":"error_code","errorClass":"SandboxWorkerCapabilityError","httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/worker.ts","lineNumber":287,"sourceCode":"}\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;\n  const attempts = Math.max(1, Math.ceil(timeoutMs / 1000));\n  await runInSandbox(\n    sandbox,\n    [\n      'i=0',\n      `while ! mkdir ${shellQuote(lock)} 2>/dev/null; do`,\n      `  if [ \"$i\" -ge ${attempts} ]; then echo ${shellQuote(`${label} lock timeout`)} >&2; exit 1; fi`,","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/worker.ts#L269-L305","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read error.cause.message — it contains the raw stderr/stdout detail; use it to identify the real sandbox-side failure.","Re-run the deploy with debug logging of sandbox command output to see why the script exited nonzero without a marker.","Test the sandbox provider with a trivial executeCommand call; if basic commands fail, fix the sandbox image/runtime first.","As a workaround, deploy without resourceLimits, or choose a sandbox provider whose exec preserves stdout/stderr."],"exampleFix":"// before\nconst deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { openFiles: 256 } });\n// after\nlet deployment;\ntry {\n  deployment = await deployWorkerToSandbox({ sandbox, command: 'node', resourceLimits: { openFiles: 256 } });\n} catch (error) {\n  if (error instanceof SandboxWorkerCapabilityError) {\n    console.error('preflight detail:', error.cause?.message); // raw stderr/stdout from the sandbox\n  }\n  throw error;\n}","handlingStrategy":"try-catch","validationCode":"// Verify basic shell behavior in the sandbox before requesting resource limits:\nconst probe = await sandbox.executeCommand('sh -c \"uname -s; ls /proc/self/stat; command -v setsid\"');\nif (probe.exitCode !== 0) {\n  throw new Error('Sandbox shell cannot run preflight; do not request resourceLimits on this provider.');\n}","typeGuard":"function isCapabilityError(error) {\n  return error instanceof Object && 'code' in error && typeof error.code === 'string';\n}\nfunction hasDiagnosticCause(error) {\n  return error instanceof Object && 'cause' in error && error.cause instanceof Error;\n}","tryCatchPattern":"try {\n  return await deployWorkerToSandbox(options);\n} catch (error) {\n  if (isCapabilityError(error) && hasDiagnosticCause(error)) {\n    console.error('Preflight failed without a capability marker. Raw detail:', error.cause.message);\n    // Option: fall back to deploying without resourceLimits\n    const { resourceLimits, ...rest } = options;\n    if (resourceLimits) return deployWorkerToSandbox(rest);\n  }\n  throw error;\n}","preventionTips":["Use a standard Linux sandbox image with /bin/sh, /proc mounted, and setsid available.","Ensure the provider preserves command stdout/stderr so the capability marker survives.","Probe the sandbox with a trivial shell script before enabling resourceLimits in config.","Log error.cause.message — it carries the preflight's raw stderr/stdout for diagnosis."],"tags":["sandbox","capability","resource-limits","shell"],"backgroundTag":"sandbox-command-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}