{"record":{"id":"70e4a5b612fa795a","repo":"mastra-ai/mastra","slug":"feature-not-supported-70e4a5","errorCode":"FEATURE_NOT_SUPPORTED","errorMessage":"Sandbox does not support processes","messagePattern":"Sandbox does not support processes","errorType":"error_code","errorClass":"SandboxFeatureNotSupportedError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/tools/kill-process.ts","lineNumber":36,"sourceCode":"  inputSchema: z.object({\n    pid: z.string().describe('The process ID of the background process to kill'),\n  }),\n  execute: async ({ pid }, context) => {\n    const { workspace, sandbox } = requireSandbox(context);\n    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.KILL_PROCESS);\n\n    const span = startWorkspaceSpan(context, workspace, {\n      category: 'sandbox',\n      operation: 'killProcess',\n      input: { pid },\n      attributes: { sandboxProvider: sandbox.provider },\n    });\n\n    const toolCallId = context?.agent?.toolCallId;\n\n    try {\n      if (!sandbox.processes) {\n        throw new SandboxFeatureNotSupportedError('processes');\n      }\n      // Snapshot output before kill\n      const handle = await sandbox.processes.get(pid);\n\n      // Emit command info so the UI can display the original command\n      if (handle?.command) {\n        await context?.writer?.custom({\n          type: 'data-sandbox-command',\n          data: { command: handle.command, pid, toolCallId },\n        });\n      }\n\n      const killed = await sandbox.processes.kill(pid);\n\n      if (!killed) {\n        await context?.writer?.custom({\n          type: 'data-sandbox-exit',\n          data: { exitCode: handle?.exitCode ?? -1, success: false, killed: false, toolCallId },","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/kill-process.ts#L18-L54","documentation":"Killing a process requires a sandbox that exposes a process management API. When the resolved sandbox's `processes` property is absent (the sandbox backend doesn't implement process listing/kill), the tool throws `SandboxFeatureNotSupportedError('processes')` instead of failing at runtime deep in the call. This is a feature-capability guard: not all sandbox providers implement every subsystem.","triggerScenarios":"Calling the kill-process workspace tool when `sandbox.processes` is undefined — e.g. a sandbox class constructed without process support, a provider that only implements filesystem operations, or a sandbox resolved by a dynamic resolver that returns a minimal sandbox instance.","commonSituations":"Using a lightweight or custom sandbox implementation that omits the `processes` subsystem; switching sandbox providers and calling process tools that the new provider doesn't support; a resolver returning a bare filesystem-only sandbox.","solutions":["Verify the sandbox instance passed to the Workspace actually implements `processes` (check `sandbox.processes !== undefined`) before enabling process tools","Use a sandbox implementation that supports process management (e.g. the full Docker/local sandbox rather than a filesystem-only one)","Gate the `killProcess` tool out of your tools config when the sandbox lacks process support, or feature-detect at startup and log a clear configuration error"],"exampleFix":"// before\nconst workspace = new Workspace({ sandbox: new FilesystemOnlySandbox() });\n// tools include kill-process -> throws at call time\n\n// after\nconst sandbox = new DockerSandbox(); // implements processes API\nconst workspace = new Workspace({ sandbox });","handlingStrategy":"validation","validationCode":"if (!sandbox.processes) {\n  throw new Error('Configured sandbox does not support process management; enable a sandbox with `processes` support or disable process tools.');\n}","typeGuard":"function supportsProcesses(sandbox) {\n  return typeof sandbox === 'object' && sandbox !== null && 'processes' in sandbox && sandbox.processes != null;\n}","tryCatchPattern":"try {\n  await killProcessTool.execute({ pid }, ctx);\n} catch (err) {\n  if (err?.code === 'FEATURE_NOT_SUPPORTED') {\n    return { skipped: true, reason: 'sandbox lacks process support' };\n  }\n  throw err;\n}","preventionTips":["Feature-detect `sandbox.processes` at workspace setup and exclude process tools when absent","Prefer sandbox implementations documented to support process management when process tools are needed","Add a startup assertion/test that the chosen sandbox class implements all subsystems your tools config requires"],"tags":["sandbox","processes","feature-not-supported","workspace-tools"],"backgroundTag":"sandbox-feature-not-supported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}