{"record":{"id":"6d8b113e9113e01b","repo":"n8n-io/n8n","slug":"agent-browser-action-failed","errorCode":null,"errorMessage":"agent-browser action failed","messagePattern":"agent-browser action failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/mcp-browser/src/adapters/agent-browser.ts","lineNumber":152,"sourceCode":"\t\t\t\t\t? target.ref\n\t\t\t\t\t: `@${target.ref}`\n\t\t\t\t: target.selector;\n\t\treturn AgentBrowserAdapter.assertSafeArg(value, 'element target');\n\t}\n\n\tprivate static assertSafeArg(value: string, role: string): string {\n\t\tif (value.length > 1 && value.startsWith('-')) {\n\t\t\tthrow new Error(\n\t\t\t\t`Invalid ${role}: argument cannot start with '-' (got: ${JSON.stringify(value.slice(0, 20))})`,\n\t\t\t);\n\t\t}\n\t\treturn value;\n\t}\n\n\tprivate async runAction(args: string[]): Promise<void> {\n\t\tconst resp = await this.run(args);\n\t\tif (!resp.success) {\n\t\t\tthrow new Error(resp.error ?? 'agent-browser action failed');\n\t\t}\n\t}\n\n\tprivate async navResult(pageId: string): Promise<NavigateResult> {\n\t\tconst tabs = await this.refreshTabs();\n\t\tconst tab = tabs.find((t) => t.tabId === pageId);\n\t\treturn { title: tab?.title ?? '', url: tab?.url ?? '', status: 0 };\n\t}\n\n\t/** Kill the agent-browser session directly (no --cdp, no relay dependency). */\n\tprivate async killSession(): Promise<void> {\n\t\ttry {\n\t\t\tawait execFileAsync('agent-browser', ['--session', SESSION_NAME, 'close'], {\n\t\t\t\ttimeout: 5_000,\n\t\t\t});\n\t\t} catch {\n\t\t\t// no existing session — that's fine\n\t\t}","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/mcp-browser/src/adapters/agent-browser.ts#L134-L170","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the gateway logs for the run() args that produced the failure — the 'run:' debug line shows the command.","Retry after taking a fresh snapshot — the target ref may be stale.","Upgrade or pin the agent-browser CLI version to match what the adapter expects.","If the issue persists, reproduce the exact agent-browser CLI invocation manually to see the raw JSON response."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isAgentBrowserActionFailure(error: unknown): boolean {\n  return error instanceof Error && /agent-browser action failed/.test(error.message);\n}","tryCatchPattern":"try {\n  await adapter.click(pageId, target);\n} catch (err) {\n  if (isAgentBrowserActionFailure(err)) {\n    await adapter.snapshot(pageId); // refresh refs\n    await adapter.click(pageId, target);\n  } else throw err;\n}","preventionTips":["Take a fresh snapshot before retrying — the failure often indicates a stale ref.","Pin the agent-browser CLI version to match the adapter's response shape.","Log the run() args from the 'run:' debug line to reproduce failures."],"tags":["mcp-browser","agent-browser","interaction","cli"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}