{"record":{"id":"c8c4dbd5aefcc8fb","repo":"n8n-io/n8n","slug":"agent-browser-failed","errorCode":null,"errorMessage":"agent-browser failed","messagePattern":"agent-browser failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@n8n/mcp-browser/src/adapters/agent-browser.ts","lineNumber":98,"sourceCode":"\t\ttry {\n\t\t\tconst { stdout } = await execFileAsync(\n\t\t\t\t'agent-browser',\n\t\t\t\t['--json', '--session', SESSION_NAME, ...cdpArgs, ...args],\n\t\t\t\t{ encoding: 'utf8', timeout: timeoutMs },\n\t\t\t);\n\t\t\tconst out = stdout?.trim() ?? '';\n\t\t\tif (!out) return { success: true };\n\t\t\ttry {\n\t\t\t\treturn JSON.parse(out) as AgentBrowserResponse;\n\t\t\t} catch {\n\t\t\t\treturn { success: true };\n\t\t\t}\n\t\t} catch (execError) {\n\t\t\tconst e = execError as { stderr?: string; stdout?: string; message?: string };\n\t\t\tconst detail = e.stderr?.trim() ?? e.stdout?.trim();\n\n\t\t\tlog.error('agent-browser execution error', { error: e });\n\t\t\tthrow new Error(detail ?? e.message ?? 'agent-browser failed');\n\t\t}\n\t}\n\n\tprivate async refreshTabs(): Promise<TabData[]> {\n\t\ttry {\n\t\t\tconst response = await this.run(['tab', 'list']);\n\t\t\tconst data = response.data as { tabs?: TabData[] } | undefined;\n\t\t\tthis.tabCache = data?.tabs ?? [];\n\t\t\tfor (const tab of this.tabCache) {\n\t\t\t\tthis.urlCache.set(tab.tabId, tab.url);\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tlog.debug('refreshTabs failed, assuming no active tabs available', { error: e });\n\t\t\tthis.tabCache = [];\n\t\t\tthis.urlCache.clear();\n\t\t}\n\t\treturn this.tabCache;\n\t}","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/mcp-browser/src/adapters/agent-browser.ts#L80-L116","documentation":"Thrown by AgentBrowserAdapter.run when the underlying `agent-browser` CLI process (spawned via execFileAsync) exits with an error AND there is no stderr, no stdout, and no message on the error object. The literal 'agent-browser failed' is the last-resort fallback detail. The full exec error is logged at error level before throwing.","triggerScenarios":"Any call that invokes this.run([...]) — snapshot, click, navigate, eval, tab list, etc. — where the `agent-browser` binary spawn fails with ENOENT (binary not on PATH), is killed by a signal with no output, times out, or crashes producing zero stderr/stdout.","commonSituations":"The `agent-browser` CLI is not installed or not on PATH (ENOENT); the binary was uninstalled/renamed during a version change; the process was OOM-killed with no output; a system-level sandbox blocks exec; the session name is stale and the CLI exits silently.","solutions":["Verify `agent-browser` is installed and on PATH: run `which agent-browser` from the gateway process's environment.","Reinstall or upgrade the agent-browser package to match the adapter's expected CLI version.","Check the gateway process logs for the 'agent-browser execution error' line which carries the raw error object (more detail than the thrown message).","If ENOENT, fix the PATH so the gateway process can resolve the binary."],"exampleFix":"// before — relying on the default PATH\nconst adapter = new AgentBrowserAdapter(config);\n\n// after — ensure the binary is resolvable before launch\nimport { existsSync } from 'node:fs';\nif (!existsSync('/usr/local/bin/agent-browser')) {\n  throw new Error('agent-browser CLI not installed; install it before connecting.');\n}","handlingStrategy":"try-catch","validationCode":"import { access } from 'node:fs/promises';\n\nasync function isAgentBrowserInstalled(): Promise<boolean> {\n  try { await access('/usr/local/bin/agent-browser'); return true; } catch { return false; }\n}","typeGuard":"function isAgentBrowserSpawnError(error: unknown): boolean {\n  return error instanceof Error && (error.message === 'agent-browser failed'\n    || /agent-browser execution error/.test(error.message));\n}","tryCatchPattern":"try {\n  await adapter.snapshot(pageId);\n} catch (err) {\n  if (isAgentBrowserSpawnError(err)) {\n    // prompt user to install agent-browser, then retry once\n  }\n  throw err;\n}","preventionTips":["Verify `agent-browser` is on the gateway process's PATH at startup.","Pin the agent-browser CLI version to match the adapter.","Log the full exec error object — the thrown fallback message hides detail."],"tags":["mcp-browser","agent-browser","cli","spawn","exec"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}