n8n-io/n8n · error · Error

agent-browser action failed

Error message

agent-browser action failed

What it means

Thrown by AgentBrowserAdapter.runAction as the fallback message when the agent-browser CLI returned a JSON response with success === false but no `error` field. runAction is the helper used by click, dblclick, hover, type, fill, press, scrollintoview, scroll. The literal 'agent-browser action failed' is only used when resp.error is null/undefined.

Source

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

					? target.ref
					: `@${target.ref}`
				: target.selector;
		return AgentBrowserAdapter.assertSafeArg(value, 'element target');
	}

	private static assertSafeArg(value: string, role: string): string {
		if (value.length > 1 && value.startsWith('-')) {
			throw new Error(
				`Invalid ${role}: argument cannot start with '-' (got: ${JSON.stringify(value.slice(0, 20))})`,
			);
		}
		return value;
	}

	private async runAction(args: string[]): Promise<void> {
		const resp = await this.run(args);
		if (!resp.success) {
			throw new Error(resp.error ?? 'agent-browser action failed');
		}
	}

	private async navResult(pageId: string): Promise<NavigateResult> {
		const tabs = await this.refreshTabs();
		const tab = tabs.find((t) => t.tabId === pageId);
		return { title: tab?.title ?? '', url: tab?.url ?? '', status: 0 };
	}

	/** Kill the agent-browser session directly (no --cdp, no relay dependency). */
	private async killSession(): Promise<void> {
		try {
			await execFileAsync('agent-browser', ['--session', SESSION_NAME, 'close'], {
				timeout: 5_000,
			});
		} catch {
			// no existing session — that's fine
		}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Check the gateway logs for the run() args that produced the failure — the 'run:' debug line shows the command.
2. Retry after taking a fresh snapshot — the target ref may be stale.
3. Upgrade or pin the agent-browser CLI version to match what the adapter expects.
4. If the issue persists, reproduce the exact agent-browser CLI invocation manually to see the raw JSON response.

function isAgentBrowserActionFailure(error: unknown): boolean {
  return error instanceof Error && /agent-browser action failed/.test(error.message);
}

try {
  await adapter.click(pageId, target);
} catch (err) {
  if (isAgentBrowserActionFailure(err)) {
    await adapter.snapshot(pageId); // refresh refs
    await adapter.click(pageId, target);
  } else throw err;
}

When it happens

Trigger: Any runAction-backed method (click, hover, type, fill, press, scroll) where the `agent-browser` CLI exits cleanly, returns valid JSON, but the JSON is { success: false } with no `error` string. This is an upstream CLI contract violation — the CLI signaled failure without explaining why.

Common situations: An agent-browser version mismatch where the CLI returns success:false on a soft failure (element not found, click intercepted) but omits the error field; a transient element-interaction issue where the CLI drops the error message; the target element is not actionable and the CLI's response shape changed.

Related errors

• agent-browser failed
• select failed
• Page not found: ${pageId}
• Invalid ${role}: argument cannot start with '-' (got: ${JSON
• No executable path for ${browser}

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