{"record":{"id":"b9306b616411ae38","repo":"mastra-ai/mastra","slug":"processes","errorCode":null,"errorMessage":"processes","messagePattern":"processes","errorType":"exception","errorClass":"SandboxFeatureNotSupportedError","httpStatus":null,"severity":"error","filePath":"packages/core/src/tools/code-mode/transport.ts","lineNumber":34,"sourceCode":"\nimport { SandboxFeatureNotSupportedError } from '../../workspace/errors';\nimport { buildRunner, buildProgramModule, FRAME_PREFIX } from './runner';\nimport { sanitizeToolId } from './stub-generator';\nimport type { CodeModeRunnerFrame, CodeModeToolResult, CodeModeTransport } from './types';\n\n/**\n * Default transport: writes the runner to a temp dir, spawns\n * `node <runner>`, and bridges RPC over stdio.\n */\nexport class StdioCodeModeTransport implements CodeModeTransport {\n  async run(opts: Parameters<CodeModeTransport['run']>[0]): Promise<CodeModeToolResult> {\n    const { sandbox, program, toolIds, dispatch, timeout, abortSignal, onExternalCall, onExternalResult } = opts;\n\n    if (!sandbox) {\n      throw new Error('StdioCodeModeTransport requires a sandbox');\n    }\n    if (!sandbox.processes) {\n      throw new SandboxFeatureNotSupportedError('processes');\n    }\n\n    const externals = toolIds.map(toolId => ({ toolId, externalName: sanitizeToolId(toolId) }));\n    const allowList = new Set(toolIds);\n\n    const dir = await mkdtemp(join(tmpdir(), 'mastra-code-mode-'));\n    const suffix = randomBytes(4).toString('hex');\n    // The model's TypeScript program is written to its own .ts module; node\n    // strips the type annotations when the runner imports it (see the\n    // --experimental-strip-types flag on the spawn below).\n    const programPath = join(dir, `program-${suffix}.ts`);\n    await writeFile(programPath, buildProgramModule(program), 'utf8');\n    const runnerSource = buildRunner({ programModule: pathToFileURL(programPath).href, externals });\n    const runnerPath = join(dir, `runner-${suffix}.mjs`);\n    await writeFile(runnerPath, runnerSource, 'utf8');\n\n    const logs: string[] = [];\n    let done: CodeModeToolResult | undefined;","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/tools/code-mode/transport.ts#L16-L52","documentation":"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.","triggerScenarios":"Passing a sandbox implementation that only supports filesystem or other features (no processes API) to StdioCodeModeTransport.run or createCodeMode using the stdio transport.","commonSituations":"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.","solutions":["Use a sandbox that supports the processes API (e.g. LocalSandbox) with the stdio transport.","Switch to a transport that does not require processes if your sandbox cannot spawn processes.","Feature-check sandbox.processes before configuring Code Mode and surface a clear config error upstream."],"exampleFix":"// before\ncreateCodeMode({ tools, sandbox: myFsOnlySandbox }); // no .processes\n// after\ncreateCodeMode({ tools, sandbox: new LocalSandbox() });","handlingStrategy":"type-guard","validationCode":"if (sandbox && !('processes' in sandbox) ) {\n  throw new Error('Selected sandbox does not support processes; required by StdioCodeModeTransport');\n}","typeGuard":"function supportsProcesses(s: unknown): s is { processes: NonNullable<unknown> } {\n  return typeof s === 'object' && s !== null && 'processes' in s && (s as any).processes != null;\n}","tryCatchPattern":"try {\n  await transport.run({ sandbox, ...rest });\n} catch (e) {\n  if (e instanceof SandboxFeatureNotSupportedError && e.feature === 'processes') {\n    // switch to LocalSandbox or a process-capable sandbox\n  } else throw e;\n}","preventionTips":["Verify sandbox feature support (processes) before choosing the stdio transport.","Prefer LocalSandbox for Code Mode unless you know your sandbox spawns processes.","Document sandbox capability requirements next to transport selection."],"tags":["code-mode","sandbox","processes","feature-support"],"backgroundTag":"sandbox-feature-not-supported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}