mastra-ai/mastra · error · SandboxFeatureNotSupportedError

FEATURE_NOT_SUPPORTED

FEATURE_NOT_SUPPORTED

Error message

Sandbox does not support processes

What it means

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.

Source

Thrown at packages/core/src/workspace/tools/kill-process.ts:36

  inputSchema: z.object({
    pid: z.string().describe('The process ID of the background process to kill'),
  }),
  execute: async ({ pid }, context) => {
    const { workspace, sandbox } = requireSandbox(context);
    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.KILL_PROCESS);

    const span = startWorkspaceSpan(context, workspace, {
      category: 'sandbox',
      operation: 'killProcess',
      input: { pid },
      attributes: { sandboxProvider: sandbox.provider },
    });

    const toolCallId = context?.agent?.toolCallId;

    try {
      if (!sandbox.processes) {
        throw new SandboxFeatureNotSupportedError('processes');
      }
      // Snapshot output before kill
      const handle = await sandbox.processes.get(pid);

      // Emit command info so the UI can display the original command
      if (handle?.command) {
        await context?.writer?.custom({
          type: 'data-sandbox-command',
          data: { command: handle.command, pid, toolCallId },
        });
      }

      const killed = await sandbox.processes.kill(pid);

      if (!killed) {
        await context?.writer?.custom({
          type: 'data-sandbox-exit',
          data: { exitCode: handle?.exitCode ?? -1, success: false, killed: false, toolCallId },

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the sandbox instance passed to the Workspace actually implements `processes` (check `sandbox.processes !== undefined`) before enabling process tools
2. Use a sandbox implementation that supports process management (e.g. the full Docker/local sandbox rather than a filesystem-only one)
3. 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

Example fix

// before
const workspace = new Workspace({ sandbox: new FilesystemOnlySandbox() });
// tools include kill-process -> throws at call time

// after
const sandbox = new DockerSandbox(); // implements processes API
const workspace = new Workspace({ sandbox });

if (!sandbox.processes) {
  throw new Error('Configured sandbox does not support process management; enable a sandbox with `processes` support or disable process tools.');
}

function supportsProcesses(sandbox) {
  return typeof sandbox === 'object' && sandbox !== null && 'processes' in sandbox && sandbox.processes != null;
}

try {
  await killProcessTool.execute({ pid }, ctx);
} catch (err) {
  if (err?.code === 'FEATURE_NOT_SUPPORTED') {
    return { skipped: true, reason: 'sandbox lacks process support' };
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• processes
• FEATURE_NOT_SUPPORTED
• execa is not available in Cloudflare Workers
• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" did not expose a publ

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