mastra-ai/mastra · error · IsolationUnavailableError

Isolation backend '${requestedIsolation}' 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).

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)

Solutions

  1. Install/enable the requested isolation backend (e.g. install Docker and ensure the daemon is running)
  2. Read the detection message in the error to see exactly what's missing and fix that
  3. Fall back to `isolation: 'none'` (the default) if you don't strictly need isolation
  4. 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

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.