mastra-ai/mastra · error · IsolationUnavailableError

Isolation backend ' ' is not available

Error message

Isolation backend '${requestedIsolation}' is not available

What it means

The LocalSandbox constructor fails fast when `options.isolation` requests a backend (e.g. a container/VM isolation) that is not available on the current machine. It calls isIsolationAvailable() and throws IsolationUnavailableError including detection details about why the backend is unavailable (binary missing, no permissions, unsupported platform).

Solutions

Install/enable the requested isolation backend (e.g. install Docker and ensure the daemon is running)
Read the detection message in the error to see exactly what's missing and fix that
Fall back to `isolation: 'none'` (the default) if you don't strictly need isolation
Probe availability first with detectIsolation()/isIsolationAvailable() before constructing the sandbox

Example fix

// before
const sandbox = new LocalSandbox({ isolation: 'docker' });
// after
import { isIsolationAvailable } from '...';
const isolation = isIsolationAvailable('docker') ? 'docker' : 'none';
if (isolation === 'none') console.warn('Docker unavailable, running without isolation');
const sandbox = new LocalSandbox({ isolation });

Defensive patterns

Strategy: fallback

Validate before calling

import { isIsolationAvailable, detectIsolation } from '...';
const requested = options.isolation ?? 'none';
if (requested !== 'none' && !isIsolationAvailable(requested)) {
  console.warn(`${requested} isolation unavailable: ${detectIsolation().message}; using 'none'`);
  options = { ...options, isolation: 'none' };
}

Try / catch

let sandbox: LocalSandbox;
try {
  sandbox = new LocalSandbox({ isolation: 'docker' });
} catch (err) {
  if (err instanceof IsolationUnavailableError) {
    console.warn(`Isolation '${err.backend}' unavailable (${err.message}); falling back to none`);
    sandbox = new LocalSandbox({ isolation: 'none' });
  } else throw err;
}

Prevention

Probe detectIsolation() at app startup and log the chosen isolation mode
Make isolation a config option with validation against availability before constructing sandboxes
In CI, install the required runtime (e.g. Docker) or explicitly pin isolation: 'none'

When it happens

Trigger: Constructing `new LocalSandbox({ isolation: 'docker' })` (or similar) on a machine without the isolation runtime installed, without daemon access, or on an unsupported OS. Default is 'none', so this only fires when isolation is explicitly requested.

Common situations: CI runners without Docker; local dev machines lacking the container runtime; WSL/macOS hosts where the isolation backend isn't supported; running as a user without permission to talk to the container daemon.

Related errors

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

Appendix: source

Thrown at packages/core/src/workspace/sandbox/local-sandbox.ts:225

  /** Refcount for isolation paths added by mounts (not present in `_initialReadWritePaths`). */
  private _mountIsolationRefCount = new Map<string, number>();
  /** Normalized mount path → canonical isolation path recorded for that mount. */
  private _mountPathToIsolationPath = new Map<string, string>();
  /** Named checkpoint to seed from on start and persist to on snapshot. */
  private readonly _checkpointName?: string;
  /** Boot-only fallback checkpoint used when `_checkpointName` has no state. */
  private readonly _seedCheckpointName?: string;
  /** Directory where named checkpoints live. */
  private readonly _checkpointsDirectory: string;
  /** Chains snapshot() calls so concurrent captures never interleave. */
  private _snapshotChain: Promise<void> = Promise.resolve();

  constructor(options: LocalSandboxOptions = {}) {
    // Validate isolation backend before super (fail fast)
    const requestedIsolation = options.isolation ?? 'none';
    if (requestedIsolation !== 'none' && !isIsolationAvailable(requestedIsolation)) {
      const detection = detectIsolation();
      throw new IsolationUnavailableError(requestedIsolation, detection.message);
    }

    super({
      ...options,
      name: 'LocalSandbox',
      processes: new LocalProcessManager({ env: options.env ?? {} }),
    });

    this.id = options.id ?? this.generateId();
    this._createdAt = new Date();
    this.workingDirectory = expandTilde(options.workingDirectory ?? path.join(process.cwd(), '.sandbox'));
    this.env = options.env ?? {};
    this._nativeSandboxConfig = {
      ...options.nativeSandbox,
      readWritePaths: [...(options.nativeSandbox?.readWritePaths ?? [])],
      readOnlyPaths: [...(options.nativeSandbox?.readOnlyPaths ?? [])],
    };
    this._initialReadWritePaths = new Set(this._nativeSandboxConfig.readWritePaths ?? []);

View on GitHub (pinned to 75dd419e61)