{"record":{"id":"3986ac3ab5803035","repo":"mastra-ai/mastra","slug":"feature-not-supported-3986ac","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/get-process-output.ts","lineNumber":46,"sourceCode":"        'If true, block until the process exits and return the final output. Useful for short-lived background commands where you want to wait for the result.',\n      ),\n  }),\n  execute: async ({ pid, tail, wait: shouldWait }, context) => {\n    const { workspace, sandbox } = requireSandbox(context);\n    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.GET_PROCESS_OUTPUT);\n\n    const span = startWorkspaceSpan(context, workspace, {\n      category: 'sandbox',\n      operation: 'getProcessOutput',\n      input: { pid, tail, wait: shouldWait },\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      const handle = await sandbox.processes.get(pid);\n      if (!handle) {\n        span.end({ success: false });\n        return `No background process found with PID ${pid}.${getDynamicSandboxCacheKeyHint(workspace)}`;\n      }\n\n      // Emit process info so the UI can display the 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      // If wait requested, block until process exits with streaming callbacks.\n      // The run's abortSignal is forwarded so aborting the run (e.g. a user\n      // stop) interrupts a blocking wait instead of outliving the turn: the","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/get-process-output.ts#L28-L64","documentation":"Thrown by the get-process-output tool when the workspace's sandbox exists but has no `processes` implementation, so background process handles cannot be retrieved. Uses SandboxFeatureNotSupportedError with code FEATURE_NOT_SUPPORTED.","triggerScenarios":"Calling get-process-output with a PID on a sandbox lacking `sandbox.processes` (e.g. a minimal sandbox provider that cannot manage background processes).","commonSituations":"Using run-command-in-background style flows against a sandbox that doesn't track processes; provider swap after which process APIs disappeared; stale tool registrations for a sandbox type without process support.","solutions":["Use a sandbox provider that implements the `processes` interface","Expose get-process-output only when sandbox.processes exists at registration time","Poll output from the command tool itself instead of background PIDs when process APIs are unavailable","Handle FEATURE_NOT_SUPPORTED and return the output via an alternate mechanism"],"exampleFix":"// before\nconst sandbox = createBasicSandbox();\n// after\nconst sandbox = createProcessCapableSandbox(); // exposes sandbox.processes","handlingStrategy":"type-guard","validationCode":"if (!workspace.sandbox?.processes) {\n  throw new Error('background process tools unavailable');\n}","typeGuard":"function hasProcesses(s: WorkspaceSandbox): s is WorkspaceSandbox & { processes: NonNullable<WorkspaceSandbox['processes']> } {\n  return typeof (s as any).processes === 'object' && (s as any).processes !== null;\n}","tryCatchPattern":"try {\n  return await getProcessOutputTool.execute(ctx);\n} catch (e: any) {\n  if (e?.code === 'FEATURE_NOT_SUPPORTED' || /does not support processes/i.test(e?.message ?? '')) {\n    return { error: 'Sandbox does not support background processes.' };\n  }\n  throw e;\n}","preventionTips":["Only expose process tools for sandboxes implementing `processes`","Verify provider capabilities when swapping sandbox implementations","Avoid background-PID workflows on minimal sandboxes","Add capability checks to agent tool allowlists"],"tags":["sandbox","processes","feature-flags","background-process"],"backgroundTag":"sandbox-feature-not-supported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}