mastra-ai/mastra · error · SandboxNotAvailableError

NO_SANDBOX

NO_SANDBOX

Error message

Workspace does not have a sandbox configured

What it means

Thrown by requireSandbox when the workspace has no `sandbox` configured. Sandbox-dependent tools (processes, computer use) require a WorkspaceSandbox; SandboxNotAvailableError carries code NO_SANDBOX.

Source

Thrown at packages/core/src/workspace/tools/helpers.ts:68

} {
  const workspace = requireWorkspace(context);
  if (!workspace.filesystem) {
    throw new FilesystemNotAvailableError();
  }
  return { workspace, filesystem: workspace.filesystem };
}

/**
 * Extract sandbox from workspace in tool execution context.
 * Throws if workspace or sandbox is not available.
 */
export function requireSandbox(context: ToolExecutionContext): {
  workspace: Workspace;
  sandbox: WorkspaceSandbox;
} {
  const workspace = requireWorkspace(context);
  if (!workspace.sandbox) {
    throw new SandboxNotAvailableError();
  }
  return { workspace, sandbox: workspace.sandbox };
}

export function getDynamicSandboxCacheKeyHint(workspace: Workspace): string {
  const hasResolver = workspace.hasSandboxResolver();
  const hasCacheKey = workspace.hasSandboxCacheKey();

  if (!hasResolver || hasCacheKey) return '';

  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.';
}

/**
 * Emit workspace metadata as a data chunk so the UI can render workspace info immediately.
 * Should be called at the start of every workspace tool's execute function.
 */
export async function emitWorkspaceMetadata(context: ToolExecutionContext, toolName: string) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure a sandbox: `new Workspace({ sandbox: createSandbox(...) })`
2. Register sandbox tools conditionally, only when `workspace.sandbox` exists
3. Use `getDynamicSandboxCacheKeyHint`/resolver APIs only alongside a sandbox (or sandbox resolver) setup
4. Catch NO_SANDBOX and disable execution features gracefully in your UI/agent instructions

Example fix

// before
new Workspace({ filesystem })
// after
new Workspace({ filesystem, sandbox: createLocalSandbox({ root }) })

if (!workspace.sandbox) {
  throw new Error('Execution tools require a workspace sandbox');
}

function hasSandbox(w: Workspace): w is Workspace & { sandbox: WorkspaceSandbox } {
  return !!w.sandbox;
}

try {
  return await sandboxTool.execute(ctx);
} catch (e: any) {
  if (e?.code === 'NO_SANDBOX' || /sandbox configured/i.test(e?.message ?? '')) {
    return { error: 'Add a sandbox to the workspace to use execution tools.' };
  }
  throw e;
}

When it happens

Trigger: Invoking sandbox tools (execute-command, background processes, computer tools) on a workspace created with only a filesystem (`new Workspace({ filesystem })`).

Common situations: Local-only workspaces where code-execution tools were still registered; assuming all workspace features ship by default; provider migration dropping the sandbox option.

Related errors

• NO_WORKSPACE
• NO_FILESYSTEM
• Auth0 domain and audience are required, please provide them
• Could not resolve the sandbox home directory. Pass `remoteDi
• Unknown worker resource limit: ${name}.

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