mastra-ai/mastra · error · SandboxFeatureNotSupportedError

FEATURE_NOT_SUPPORTED

FEATURE_NOT_SUPPORTED

Error message

Sandbox does not support processes

What it means

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.

Source

Thrown at packages/core/src/workspace/tools/get-process-output.ts:46

        '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.',
      ),
  }),
  execute: async ({ pid, tail, wait: shouldWait }, context) => {
    const { workspace, sandbox } = requireSandbox(context);
    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.GET_PROCESS_OUTPUT);

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

    const toolCallId = context?.agent?.toolCallId;

    try {
      if (!sandbox.processes) {
        throw new SandboxFeatureNotSupportedError('processes');
      }
      const handle = await sandbox.processes.get(pid);
      if (!handle) {
        span.end({ success: false });
        return `No background process found with PID ${pid}.${getDynamicSandboxCacheKeyHint(workspace)}`;
      }

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

      // If wait requested, block until process exits with streaming callbacks.
      // The run's abortSignal is forwarded so aborting the run (e.g. a user
      // stop) interrupts a blocking wait instead of outliving the turn: the

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a sandbox provider that implements the `processes` interface
2. Expose get-process-output only when sandbox.processes exists at registration time
3. Poll output from the command tool itself instead of background PIDs when process APIs are unavailable
4. Handle FEATURE_NOT_SUPPORTED and return the output via an alternate mechanism

Example fix

// before
const sandbox = createBasicSandbox();
// after
const sandbox = createProcessCapableSandbox(); // exposes sandbox.processes

if (!workspace.sandbox?.processes) {
  throw new Error('background process tools unavailable');
}

function hasProcesses(s: WorkspaceSandbox): s is WorkspaceSandbox & { processes: NonNullable<WorkspaceSandbox['processes']> } {
  return typeof (s as any).processes === 'object' && (s as any).processes !== null;
}

try {
  return await getProcessOutputTool.execute(ctx);
} catch (e: any) {
  if (e?.code === 'FEATURE_NOT_SUPPORTED' || /does not support processes/i.test(e?.message ?? '')) {
    return { error: 'Sandbox does not support background processes.' };
  }
  throw e;
}

When it happens

Trigger: Calling get-process-output with a PID on a sandbox lacking `sandbox.processes` (e.g. a minimal sandbox provider that cannot manage background processes).

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

Related errors

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

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