n8n-io/n8n · error

agent-browser failed

Error message

agent-browser failed

What it means

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.

Source

Thrown at packages/@n8n/mcp-browser/src/adapters/agent-browser.ts:98

		try {
			const { stdout } = await execFileAsync(
				'agent-browser',
				['--json', '--session', SESSION_NAME, ...cdpArgs, ...args],
				{ encoding: 'utf8', timeout: timeoutMs },
			);
			const out = stdout?.trim() ?? '';
			if (!out) return { success: true };
			try {
				return JSON.parse(out) as AgentBrowserResponse;
			} catch {
				return { success: true };
			}
		} catch (execError) {
			const e = execError as { stderr?: string; stdout?: string; message?: string };
			const detail = e.stderr?.trim() ?? e.stdout?.trim();

			log.error('agent-browser execution error', { error: e });
			throw new Error(detail ?? e.message ?? 'agent-browser failed');
		}
	}

	private async refreshTabs(): Promise<TabData[]> {
		try {
			const response = await this.run(['tab', 'list']);
			const data = response.data as { tabs?: TabData[] } | undefined;
			this.tabCache = data?.tabs ?? [];
			for (const tab of this.tabCache) {
				this.urlCache.set(tab.tabId, tab.url);
			}
		} catch (e) {
			log.debug('refreshTabs failed, assuming no active tabs available', { error: e });
			this.tabCache = [];
			this.urlCache.clear();
		}
		return this.tabCache;
	}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Verify `agent-browser` is installed and on PATH: run `which agent-browser` from the gateway process's environment.
2. Reinstall or upgrade the agent-browser package to match the adapter's expected CLI version.
3. Check the gateway process logs for the 'agent-browser execution error' line which carries the raw error object (more detail than the thrown message).
4. If ENOENT, fix the PATH so the gateway process can resolve the binary.

Example fix

// before — relying on the default PATH
const adapter = new AgentBrowserAdapter(config);

// after — ensure the binary is resolvable before launch
import { existsSync } from 'node:fs';
if (!existsSync('/usr/local/bin/agent-browser')) {
  throw new Error('agent-browser CLI not installed; install it before connecting.');
}

import { access } from 'node:fs/promises';

async function isAgentBrowserInstalled(): Promise<boolean> {
  try { await access('/usr/local/bin/agent-browser'); return true; } catch { return false; }
}

function isAgentBrowserSpawnError(error: unknown): boolean {
  return error instanceof Error && (error.message === 'agent-browser failed'
    || /agent-browser execution error/.test(error.message));
}

try {
  await adapter.snapshot(pageId);
} catch (err) {
  if (isAgentBrowserSpawnError(err)) {
    // prompt user to install agent-browser, then retry once
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• agent-browser action failed
• Page not found: ${pageId}
• Invalid ${role}: argument cannot start with '-' (got: ${JSON
• No executable path for ${browser}
• Failed to create new tab

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/c8c4dbd5aefcc8fb. Report an issue: GitHub.