mastra-ai/mastra · error · SandboxFeatureNotSupportedError

processes

Error message

processes

What it means

StdioCodeModeTransport spawns child processes, which is an optional sandbox capability. When the provided sandbox exists but does not implement the processes feature (sandbox.processes is undefined), run() throws SandboxFeatureNotSupportedError('processes') instead of failing later at spawn time.

Source

Thrown at packages/core/src/tools/code-mode/transport.ts:34

import { SandboxFeatureNotSupportedError } from '../../workspace/errors';
import { buildRunner, buildProgramModule, FRAME_PREFIX } from './runner';
import { sanitizeToolId } from './stub-generator';
import type { CodeModeRunnerFrame, CodeModeToolResult, CodeModeTransport } from './types';

/**
 * Default transport: writes the runner to a temp dir, spawns
 * `node <runner>`, and bridges RPC over stdio.
 */
export class StdioCodeModeTransport implements CodeModeTransport {
  async run(opts: Parameters<CodeModeTransport['run']>[0]): Promise<CodeModeToolResult> {
    const { sandbox, program, toolIds, dispatch, timeout, abortSignal, onExternalCall, onExternalResult } = opts;

    if (!sandbox) {
      throw new Error('StdioCodeModeTransport requires a sandbox');
    }
    if (!sandbox.processes) {
      throw new SandboxFeatureNotSupportedError('processes');
    }

    const externals = toolIds.map(toolId => ({ toolId, externalName: sanitizeToolId(toolId) }));
    const allowList = new Set(toolIds);

    const dir = await mkdtemp(join(tmpdir(), 'mastra-code-mode-'));
    const suffix = randomBytes(4).toString('hex');
    // The model's TypeScript program is written to its own .ts module; node
    // strips the type annotations when the runner imports it (see the
    // --experimental-strip-types flag on the spawn below).
    const programPath = join(dir, `program-${suffix}.ts`);
    await writeFile(programPath, buildProgramModule(program), 'utf8');
    const runnerSource = buildRunner({ programModule: pathToFileURL(programPath).href, externals });
    const runnerPath = join(dir, `runner-${suffix}.mjs`);
    await writeFile(runnerPath, runnerSource, 'utf8');

    const logs: string[] = [];
    let done: CodeModeToolResult | undefined;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a sandbox that supports the processes API (e.g. LocalSandbox) with the stdio transport.
2. Switch to a transport that does not require processes if your sandbox cannot spawn processes.
3. Feature-check sandbox.processes before configuring Code Mode and surface a clear config error upstream.

Example fix

// before
createCodeMode({ tools, sandbox: myFsOnlySandbox }); // no .processes
// after
createCodeMode({ tools, sandbox: new LocalSandbox() });

if (sandbox && !('processes' in sandbox) ) {
  throw new Error('Selected sandbox does not support processes; required by StdioCodeModeTransport');
}

function supportsProcesses(s: unknown): s is { processes: NonNullable<unknown> } {
  return typeof s === 'object' && s !== null && 'processes' in s && (s as any).processes != null;
}

try {
  await transport.run({ sandbox, ...rest });
} catch (e) {
  if (e instanceof SandboxFeatureNotSupportedError && e.feature === 'processes') {
    // switch to LocalSandbox or a process-capable sandbox
  } else throw e;
}

When it happens

Trigger: Passing a sandbox implementation that only supports filesystem or other features (no processes API) to StdioCodeModeTransport.run or createCodeMode using the stdio transport.

Common situations: Custom or restricted sandbox implementations (e.g. remote/container sandboxes without process spawning, edge runtimes, in-memory test sandboxes); swapping LocalSandbox for a cloud sandbox that lacks process support.

Related errors

• Code Mode requires a sandbox to run model-authored code, but
• StdioCodeModeTransport requires a sandbox
• FEATURE_NOT_SUPPORTED
• FEATURE_NOT_SUPPORTED
• IsolatedVmCodeModeTransport requires the --no-node-snapshot

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