{"record":{"id":"a3474136cef7c371","repo":"mastra-ai/mastra","slug":"stdiocodemodetransport-requires-a-sandbox","errorCode":null,"errorMessage":"StdioCodeModeTransport requires a sandbox","messagePattern":"StdioCodeModeTransport requires a sandbox","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/tools/code-mode/transport.ts","lineNumber":31,"sourceCode":"import { tmpdir } from 'node:os';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\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');","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/tools/code-mode/transport.ts#L13-L49","documentation":"StdioCodeModeTransport runs model-authored code in a child process, which by definition requires a sandbox handle. Its run() throws if the opts.sandbox field is absent, because there is no safe way to spawn the program without one.","triggerScenarios":"Invoking StdioCodeModeTransport.run (directly or through createCodeMode) with opts where sandbox is undefined, e.g. building a custom transport pipeline and forgetting to pass the sandbox resolved from a workspace.","commonSituations":"Custom Code Mode wiring that bypasses createCodeMode's sandbox resolution; conditionally-constructed option objects where sandbox is dropped; refactors that moved sandbox resolution out of the call site.","solutions":["Pass a sandbox in the run options, e.g. resolve it via workspace.resolveSandbox({ requestContext }) or use new LocalSandbox().","If using createCodeMode, provide sandbox: new LocalSandbox() or run within a sandbox-providing workspace (see error 1821).","Assert sandbox presence at the call site before invoking the transport."],"exampleFix":"// before\nawait transport.run({ program, toolIds, dispatch, timeout });\n// after\nawait transport.run({ sandbox: new LocalSandbox(), program, toolIds, dispatch, timeout });","handlingStrategy":"validation","validationCode":"if (!opts.sandbox) throw new Error('StdioCodeModeTransport.run requires opts.sandbox');\nawait transport.run({ ...opts, sandbox: opts.sandbox ?? new LocalSandbox() });","typeGuard":"function hasSandbox(o: { sandbox?: unknown }): o is { sandbox: NonNullable<unknown> } {\n  return o.sandbox != null;\n}","tryCatchPattern":"try {\n  await transport.run(opts);\n} catch (e) {\n  if (String(e.message).includes('requires a sandbox')) {\n    await transport.run({ ...opts, sandbox: new LocalSandbox() });\n  } else throw e;\n}","preventionTips":["Always resolve the sandbox before constructing transport run options.","Type run options so sandbox is non-optional where the transport requires it.","Centralize sandbox resolution in one helper."],"tags":["code-mode","sandbox","transport","configuration"],"backgroundTag":"missing-sandbox-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}