{"record":{"id":"3d7494167dd457ab","repo":"openclaw/openclaw","slug":"sandbox-browser-is-unavailable-enable-agents-defa","errorCode":null,"errorMessage":"Sandbox browser is unavailable. Enable agents.defaults.sandbox.browser.enabled or use target=\"host\" if allowed.","messagePattern":"Sandbox browser is unavailable\\. Enable agents\\.defaults\\.sandbox\\.browser\\.enabled or use target=\"host\" if allowed\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/browser/src/browser-tool.ts","lineNumber":263,"sourceCode":"        commands: node.commands ?? [],\n        pendingDeclaredCommands: node.pendingDeclaredCommands ?? [],\n      }\n    : null;\n}\n\nfunction resolveBrowserBaseUrl(params: {\n  target?: \"sandbox\" | \"host\";\n  sandboxBridgeUrl?: string;\n  allowHostControl?: boolean;\n}): string | undefined {\n  const cfg = getRuntimeConfig();\n  const resolved = resolveBrowserConfig(cfg.browser, cfg);\n  const normalizedSandbox = params.sandboxBridgeUrl?.trim() ?? \"\";\n  const target = params.target ?? (normalizedSandbox ? \"sandbox\" : \"host\");\n\n  if (target === \"sandbox\") {\n    if (!normalizedSandbox) {\n      throw new Error(\n        'Sandbox browser is unavailable. Enable agents.defaults.sandbox.browser.enabled or use target=\"host\" if allowed.',\n      );\n    }\n    return normalizedSandbox.replace(/\\/$/, \"\");\n  }\n\n  if (params.allowHostControl === false) {\n    throw new Error(\"Host browser control is disabled by sandbox policy.\");\n  }\n  if (!resolved.enabled) {\n    throw new Error(\n      \"Browser control is disabled. Set browser.enabled=true in ~/.openclaw/openclaw.json.\",\n    );\n  }\n  return undefined;\n}\n\n/**","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/browser/src/browser-tool.ts#L245-L281","documentation":"Thrown by resolveBrowserBaseUrl when target resolves to 'sandbox' (explicitly or by default because sandboxBridgeUrl was provided at tool creation) but no sandboxBridgeUrl is available at call time. The sandbox browser must be enabled via agents.defaults.sandbox.browser.enabled which provides the bridge URL; without it, sandbox routing is impossible.","triggerScenarios":"The browser tool was created with sandboxBridgeUrl but it is empty/whitespace at execution, or target: 'sandbox' is requested when no sandbox bridge was configured. The tool defaults target to 'sandbox' when sandboxBridgeUrl was provided at creation.","commonSituations":"Sandbox browser not enabled in config (agents.defaults.sandbox.browser.enabled is false/missing); sandbox started without the browser bridge; config drift between tool creation and execution; operator wants host browser instead.","solutions":["Enable the sandbox browser: set agents.defaults.sandbox.browser.enabled = true in openclaw.json so the bridge URL is provisioned.","Alternatively, use target: 'host' (if allowHostControl permits) to bypass the sandbox browser entirely.","Restart the sandbox/gateway after enabling so the bridge URL is injected into the tool."],"exampleFix":"// config: ~/.openclaw/openclaw.json\n// before\n{ \"agents\": { \"defaults\": { \"sandbox\": { \"browser\": { \"enabled\": false } } } } }\n\n// after\n{ \"agents\": { \"defaults\": { \"sandbox\": { \"browser\": { \"enabled\": true } } } } }\n\n// or in the tool call:\nawait browser({ action: 'snapshot', target: 'host' });","handlingStrategy":"validation","validationCode":"// Check sandbox browser config before requesting sandbox target\nimport { getRuntimeConfig } from './browser-tool.runtime.js';\nconst cfg = getRuntimeConfig();\nconst sandboxBrowserEnabled = cfg.agents?.defaults?.sandbox?.browser?.enabled === true;\n\nif (!sandboxBrowserEnabled && args.target === 'sandbox') {\n  // fall back to host or surface a config error\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Enable agents.defaults.sandbox.browser.enabled in openclaw.json if sandbox browser is needed.","Provide sandboxBridgeUrl when creating the browser tool in sandbox contexts.","Use target: 'host' (if allowed) as an alternative when sandbox browser is unavailable."],"tags":["browser","sandbox","config","policy"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}