{"record":{"id":"6dc91f1e12cd3959","repo":"mastra-ai/mastra","slug":"isolation-backend-requestedisolation-is-not-a","errorCode":null,"errorMessage":"Isolation backend '${requestedIsolation}' is not available","messagePattern":"Isolation backend '(.+?)' is not available","errorType":"exception","errorClass":"IsolationUnavailableError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/sandbox/local-sandbox.ts","lineNumber":225,"sourceCode":"  /** Refcount for isolation paths added by mounts (not present in `_initialReadWritePaths`). */\n  private _mountIsolationRefCount = new Map<string, number>();\n  /** Normalized mount path → canonical isolation path recorded for that mount. */\n  private _mountPathToIsolationPath = new Map<string, string>();\n  /** Named checkpoint to seed from on start and persist to on snapshot. */\n  private readonly _checkpointName?: string;\n  /** Boot-only fallback checkpoint used when `_checkpointName` has no state. */\n  private readonly _seedCheckpointName?: string;\n  /** Directory where named checkpoints live. */\n  private readonly _checkpointsDirectory: string;\n  /** Chains snapshot() calls so concurrent captures never interleave. */\n  private _snapshotChain: Promise<void> = Promise.resolve();\n\n  constructor(options: LocalSandboxOptions = {}) {\n    // Validate isolation backend before super (fail fast)\n    const requestedIsolation = options.isolation ?? 'none';\n    if (requestedIsolation !== 'none' && !isIsolationAvailable(requestedIsolation)) {\n      const detection = detectIsolation();\n      throw new IsolationUnavailableError(requestedIsolation, detection.message);\n    }\n\n    super({\n      ...options,\n      name: 'LocalSandbox',\n      processes: new LocalProcessManager({ env: options.env ?? {} }),\n    });\n\n    this.id = options.id ?? this.generateId();\n    this._createdAt = new Date();\n    this.workingDirectory = expandTilde(options.workingDirectory ?? path.join(process.cwd(), '.sandbox'));\n    this.env = options.env ?? {};\n    this._nativeSandboxConfig = {\n      ...options.nativeSandbox,\n      readWritePaths: [...(options.nativeSandbox?.readWritePaths ?? [])],\n      readOnlyPaths: [...(options.nativeSandbox?.readOnlyPaths ?? [])],\n    };\n    this._initialReadWritePaths = new Set(this._nativeSandboxConfig.readWritePaths ?? []);","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/sandbox/local-sandbox.ts#L207-L243","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst sandbox = new LocalSandbox({ isolation: 'docker' });\n// after\nimport { isIsolationAvailable } from '...';\nconst isolation = isIsolationAvailable('docker') ? 'docker' : 'none';\nif (isolation === 'none') console.warn('Docker unavailable, running without isolation');\nconst sandbox = new LocalSandbox({ isolation });","handlingStrategy":"fallback","validationCode":"import { isIsolationAvailable, detectIsolation } from '...';\nconst requested = options.isolation ?? 'none';\nif (requested !== 'none' && !isIsolationAvailable(requested)) {\n  console.warn(`${requested} isolation unavailable: ${detectIsolation().message}; using 'none'`);\n  options = { ...options, isolation: 'none' };\n}","typeGuard":null,"tryCatchPattern":"let sandbox: LocalSandbox;\ntry {\n  sandbox = new LocalSandbox({ isolation: 'docker' });\n} catch (err) {\n  if (err instanceof IsolationUnavailableError) {\n    console.warn(`Isolation '${err.backend}' unavailable (${err.message}); falling back to none`);\n    sandbox = new LocalSandbox({ isolation: 'none' });\n  } else throw err;\n}","preventionTips":["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'"],"tags":["sandbox","isolation","environment","configuration"],"backgroundTag":"isolation-backend-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}