{"record":{"id":"1c3996974eccaa78","repo":"openclaw/openclaw","slug":"sandbox-filesystem-bridge-is-unavailable-1c3996","errorCode":null,"errorMessage":"Sandbox filesystem bridge is unavailable.","messagePattern":"Sandbox filesystem bridge is unavailable\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"extensions/codex/src/app-server/sandbox-exec-server/runtime.ts","lineNumber":25,"sourceCode":"\n/** Returns the configured sandbox backend or fails the current JSON-RPC request. */\nexport function requireBackend(\n  execServer: OpenClawExecServer,\n): NonNullable<SandboxContext[\"backend\"]> {\n  const backend = execServer.sandbox.backend;\n  if (!backend) {\n    throw new Error(\"OpenClaw sandbox backend is unavailable.\");\n  }\n  return backend;\n}\n\n/** Returns the configured filesystem bridge or fails the current JSON-RPC request. */\nexport function requireFsBridge(\n  execServer: OpenClawExecServer,\n): NonNullable<SandboxContext[\"fsBridge\"]> {\n  const fsBridge = execServer.sandbox.fsBridge;\n  if (!fsBridge) {\n    throw new Error(\"Sandbox filesystem bridge is unavailable.\");\n  }\n  return fsBridge;\n}\n","sourceCodeStart":7,"sourceCodeEnd":29,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/codex/src/app-server/sandbox-exec-server/runtime.ts#L7-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the SandboxContext factory for your selected sandbox backend sets fsBridge alongside backend before the exec-server is acquired.","If the backend genuinely has no filesystem surface, disable filesystem-dependent Codex flows or pick a backend that provides both backend and fsBridge.","Inspect how acquireOpenClawExecServer(sandbox) is called upstream — ensure the sandbox passed in was built by a provider that populates fsBridge.","Run openclaw doctor to check the sandbox provider configuration and reported capabilities."],"exampleFix":"// before\nconst sandbox: SandboxContext = {\n  enabled: true,\n  backend: myProcessBackend,\n  // fsBridge missing\n};\n\n// after\nconst sandbox: SandboxContext = {\n  enabled: true,\n  backend: myProcessBackend,\n  fsBridge: myProcessBackend.createFsBridge(),\n};","handlingStrategy":"type-guard","validationCode":"function hasFsBridge(sandbox: SandboxContext | null): sandbox is SandboxContext & { fsBridge: NonNullable<SandboxContext['fsBridge']> } {\n  return !!sandbox && sandbox.enabled === true && !!sandbox.fsBridge;\n}\n\n// before dispatching fs/* RPCs\nif (!hasFsBridge(execServer.sandbox)) {\n  // reject the JSON-RPC request with -32601 / capability error instead of throwing\n  return sendError(socket, request.id, -32601, 'filesystem bridge unavailable');\n}","typeGuard":"import type { SandboxContext } from 'openclaw/plugin-sdk/sandbox';\n\nexport function sandboxHasFsBridge(s: SandboxContext | null | undefined): s is SandboxContext & {\n  fsBridge: NonNullable<SandboxContext['fsBridge']>;\n  backend: NonNullable<SandboxContext['backend']>;\n} {\n  return !!s && !!s.enabled && !!s.backend && !!s.fsBridge;\n}","tryCatchPattern":"try {\n  const bridge = requireFsBridge(execServer);\n  // ... use bridge\n} catch (error) {\n  if (error instanceof Error && error.message === 'Sandbox filesystem bridge is unavailable.') {\n    sendError(socket, request.id, -32601, 'filesystem bridge unavailable');\n    return;\n  }\n  throw error;\n}","preventionTips":["Validate SandboxContext has both backend and fsBridge before acquiring an exec-server.","In sandbox provider factories, treat fsBridge construction as mandatory when backend is set.","Add a contract test that every sandbox backend used with Codex yields an fsBridge.","Log which backend produced a context without fsBridge so misconfiguration is traceable."],"tags":["codex","sandbox","filesystem","exec-server","configuration"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}