{"record":{"id":"6df54a4c242747c4","repo":"mastra-ai/mastra","slug":"no-sandbox","errorCode":"NO_SANDBOX","errorMessage":"Workspace does not have a sandbox configured","messagePattern":"Workspace does not have a sandbox configured","errorType":"error_code","errorClass":"SandboxNotAvailableError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/tools/helpers.ts","lineNumber":68,"sourceCode":"} {\n  const workspace = requireWorkspace(context);\n  if (!workspace.filesystem) {\n    throw new FilesystemNotAvailableError();\n  }\n  return { workspace, filesystem: workspace.filesystem };\n}\n\n/**\n * Extract sandbox from workspace in tool execution context.\n * Throws if workspace or sandbox is not available.\n */\nexport function requireSandbox(context: ToolExecutionContext): {\n  workspace: Workspace;\n  sandbox: WorkspaceSandbox;\n} {\n  const workspace = requireWorkspace(context);\n  if (!workspace.sandbox) {\n    throw new SandboxNotAvailableError();\n  }\n  return { workspace, sandbox: workspace.sandbox };\n}\n\nexport function getDynamicSandboxCacheKeyHint(workspace: Workspace): string {\n  const hasResolver = workspace.hasSandboxResolver();\n  const hasCacheKey = workspace.hasSandboxCacheKey();\n\n  if (!hasResolver || hasCacheKey) return '';\n\n  return ' If this process was started from a dynamic sandbox resolver, configure sandboxCacheKey or have the resolver return the same sandbox for follow-up calls.';\n}\n\n/**\n * Emit workspace metadata as a data chunk so the UI can render workspace info immediately.\n * Should be called at the start of every workspace tool's execute function.\n */\nexport async function emitWorkspaceMetadata(context: ToolExecutionContext, toolName: string) {","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/helpers.ts#L50-L86","documentation":"Thrown by requireSandbox when the workspace has no `sandbox` configured. Sandbox-dependent tools (processes, computer use) require a WorkspaceSandbox; SandboxNotAvailableError carries code NO_SANDBOX.","triggerScenarios":"Invoking sandbox tools (execute-command, background processes, computer tools) on a workspace created with only a filesystem (`new Workspace({ filesystem })`).","commonSituations":"Local-only workspaces where code-execution tools were still registered; assuming all workspace features ship by default; provider migration dropping the sandbox option.","solutions":["Configure a sandbox: `new Workspace({ sandbox: createSandbox(...) })`","Register sandbox tools conditionally, only when `workspace.sandbox` exists","Use `getDynamicSandboxCacheKeyHint`/resolver APIs only alongside a sandbox (or sandbox resolver) setup","Catch NO_SANDBOX and disable execution features gracefully in your UI/agent instructions"],"exampleFix":"// before\nnew Workspace({ filesystem })\n// after\nnew Workspace({ filesystem, sandbox: createLocalSandbox({ root }) })","handlingStrategy":"type-guard","validationCode":"if (!workspace.sandbox) {\n  throw new Error('Execution tools require a workspace sandbox');\n}","typeGuard":"function hasSandbox(w: Workspace): w is Workspace & { sandbox: WorkspaceSandbox } {\n  return !!w.sandbox;\n}","tryCatchPattern":"try {\n  return await sandboxTool.execute(ctx);\n} catch (e: any) {\n  if (e?.code === 'NO_SANDBOX' || /sandbox configured/i.test(e?.message ?? '')) {\n    return { error: 'Add a sandbox to the workspace to use execution tools.' };\n  }\n  throw e;\n}","preventionTips":["Configure `sandbox` whenever execution/computer tools are registered","Gate execution tools on workspace.sandbox presence","Document which tools need sandbox vs filesystem","Smoke-test each tool set against the deployed workspace configuration"],"tags":["configuration","workspace","sandbox","missing-config"],"backgroundTag":"missing-workspace-config","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}