openclaw/openclaw · error

Sandbox filesystem bridge is unavailable.

Error message

Sandbox filesystem bridge is unavailable.

What it means

Thrown by requireFsBridge() inside the OpenClaw sandbox exec-server when a Codex app-server JSON-RPC handler needs filesystem access but execServer.sandbox.fsBridge is null/undefined. The fsBridge is the per-sandbox abstraction that translates Codex fs/* RPCs onto the real container/workspace filesystem; without it no fs/open, fs/readFile, fs/writeFile, fs/readDirectory, fs/remove, fs/copy, fs/createDirectory, or fs/getMetadata call can be serviced.

Source

Thrown at extensions/codex/src/app-server/sandbox-exec-server/runtime.ts:25

/** Returns the configured sandbox backend or fails the current JSON-RPC request. */
export function requireBackend(
  execServer: OpenClawExecServer,
): NonNullable<SandboxContext["backend"]> {
  const backend = execServer.sandbox.backend;
  if (!backend) {
    throw new Error("OpenClaw sandbox backend is unavailable.");
  }
  return backend;
}

/** Returns the configured filesystem bridge or fails the current JSON-RPC request. */
export function requireFsBridge(
  execServer: OpenClawExecServer,
): NonNullable<SandboxContext["fsBridge"]> {
  const fsBridge = execServer.sandbox.fsBridge;
  if (!fsBridge) {
    throw new Error("Sandbox filesystem bridge is unavailable.");
  }
  return fsBridge;
}

View on GitHub (pinned to 01804a7531)

Solutions

1. Verify the SandboxContext factory for your selected sandbox backend sets fsBridge alongside backend before the exec-server is acquired.
2. If the backend genuinely has no filesystem surface, disable filesystem-dependent Codex flows or pick a backend that provides both backend and fsBridge.
3. Inspect how acquireOpenClawExecServer(sandbox) is called upstream — ensure the sandbox passed in was built by a provider that populates fsBridge.
4. Run openclaw doctor to check the sandbox provider configuration and reported capabilities.

Example fix

// before
const sandbox: SandboxContext = {
  enabled: true,
  backend: myProcessBackend,
  // fsBridge missing
};

// after
const sandbox: SandboxContext = {
  enabled: true,
  backend: myProcessBackend,
  fsBridge: myProcessBackend.createFsBridge(),
};

function hasFsBridge(sandbox: SandboxContext | null): sandbox is SandboxContext & { fsBridge: NonNullable<SandboxContext['fsBridge']> } {
  return !!sandbox && sandbox.enabled === true && !!sandbox.fsBridge;
}

// before dispatching fs/* RPCs
if (!hasFsBridge(execServer.sandbox)) {
  // reject the JSON-RPC request with -32601 / capability error instead of throwing
  return sendError(socket, request.id, -32601, 'filesystem bridge unavailable');
}

import type { SandboxContext } from 'openclaw/plugin-sdk/sandbox';

export function sandboxHasFsBridge(s: SandboxContext | null | undefined): s is SandboxContext & {
  fsBridge: NonNullable<SandboxContext['fsBridge']>;
  backend: NonNullable<SandboxContext['backend']>;
} {
  return !!s && !!s.enabled && !!s.backend && !!s.fsBridge;
}

try {
  const bridge = requireFsBridge(execServer);
  // ... use bridge
} catch (error) {
  if (error instanceof Error && error.message === 'Sandbox filesystem bridge is unavailable.') {
    sendError(socket, request.id, -32601, 'filesystem bridge unavailable');
    return;
  }
  throw error;
}

When it happens

Trigger: Any Codex app-server fs/* RPC (fs/readFile, fs/writeFile, fs/readDirectory, fs/remove, fs/copy, fs/createDirectory, fs/getMetadata, fs/open) dispatched to an OpenClawExecServer whose SandboxContext.fsBridge was never populated. This happens when a sandbox backend was selected for process execution (backend truthy) but the same provider did not also supply a filesystem bridge, or the bridge failed to construct during sandbox acquisition.

Common situations: A custom or partial SandboxContext implementation that wires backend (for process/start) but leaves fsBridge undefined; a sandbox provider upgrade that regressed filesystem bridge construction; running with sandbox.enabled=true and sandbox.backend set but a backend type whose factory does not yield an fsBridge. Codex immediately exercises fs/* RPCs after environment registration, so the first file operation hits this.

Related errors

• Cannot resolve sandbox path: ${filePath}
• Sandbox filesystem bridge is unavailable.
• OpenClaw Codex exec-server uses a local loopback URL and can
• -32004
• -32600

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/1c3996974eccaa78. Report an issue: GitHub.