Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

13.6 KB
Raw Blame

Error codes

Every error code Browsentic returns, where it comes from, and what to do next.

Errors are { ok: false, error: { code, message } } at every layer. The agent receives one as a tool result marked isError, with the text CODE: message. A failed tool call never crashes a run, and the message carries the fix. In the Origin column, Daemon is Browsentic Bridge.


Connection

Code Origin Meaning and next move
EXTENSION_OFFLINE Daemon No live browser link. Open the browser, or pair. Retrying will not help
DAEMON_UNREACHABLE RemoteBridge The daemon died mid-call

Targeting a page

Code Origin Meaning and next move
TAB_UNREACHABLE Extension The page refuses content scripts, or one was just injected. Navigate to an http(s) page, or re-snapshot
NO_ACTIVE_TAB Extension No focused tab in the current window
TARGET_NOT_FOUND Content script Nothing matched; the page changed. Take a fresh snapshot
INVALID_TARGET Content script A target with neither selector nor text. role/nth only narrow
DEBUGGER_UNAVAILABLE Extension Chrome's debugger could not attach, usually because DevTools is open on that tab. Close it, or use page_clickElement instead of page_trustedClick
CAPTCHA_NOT_FOUND Extension No known captcha widget, so whatever is blocking the run is something else

Input and dispatch

Code Origin Meaning and next move
INVALID_INPUT Dispatch The input failed schema validation (zod); the message names the field
UNSUPPORTED Action The action cannot do what was asked, e.g. open a non-http(s) URL
TIMEOUT Link or action A wait expired, or the extension did not answer in the window for that action
ACTION_FAILED Action execute() threw, e.g. back with no history
PICK_CANCELLED Content script The user dismissed A-Eye without pointing at anything, or a newer pick took over the lens. Terminal: ask in words rather than asking them to point again
NO_FOCUS_SHOT Daemon browsentic_focusShot was called on a run whose instruction carried no A-Eye pick, so there is no picture to show
UNKNOWN_ACTION Registry / daemon Tool-registry skew, a reserved action reached from outside, or a browsentic_use call naming no page tool, answered with the list of guides
UNKNOWN_SKILL Daemon browsentic_openSkill was given a name no guide answers to. The message lists the guides
UNAVAILABLE Daemon None of a guide's tools are offered to this caller: captcha and diagnostics outside a Chromium browser on a computer, or a guide the phone cannot run

Diagnostics

Code Origin Meaning and next move
DIAGNOSTICS_NOT_FOUND Extension Nothing is recording, or that diagnosticsId is unknown. Console and network events exist only while attached: call page_startDiagnostics before reproducing the problem
DIAGNOSTICS_IN_PROGRESS Extension That tab is already being recorded. Read it, or stop it first
DIAGNOSTICS_LIMIT Extension Two tabs are already being recorded. Stop one
DEBUGGER_UNAVAILABLE Extension Chrome refused the attach, usually because DevTools is open on that tab. Close it and retry
UNSUPPORTED Extension A debugger-only tool was called on Firefox. A Firefox build leaves those nine off its list, so only a stale skill or recording reaches this. There is no fallback
BLOCKED Policy includeBodies: true without the network-body-read rule allowed. Metadata and headers are still available

Runs and sessions

Code Origin Meaning and next move
RUN_IN_PROGRESS AgentSession One instruction at a time per tab session; other sessions are unaffected
RUN_LIMIT AgentSession Too many sessions running at once (maxConcurrentRuns: default 3, ceiling 8)
SESSION_LIMIT Extension Eight tab sessions are already open
SESSION_TAB_CLOSED Extension Every tab this conversation was working in has been closed
TAB_IN_USE Extension That tab belongs to another Browsentic conversation
RUN_INACTIVE AgentSession The run was cancelled while a tool call was in flight
APPROVAL_TIMEOUT AgentSession A scheduled run asked for approval and nobody answered within ten minutes, so the action was declined. The agent is told to stop and say what it was about to do
APPROVAL_PENDING AgentSession The user has not answered an approval yet, and the agent's CLI would abandon the call before they do (Cursor CLI, at 60 s). The request stays on screen: make the same call again, with the same input, to keep waiting. Any other call withdraws it
RESULT_TOO_LARGE MCP server The call went through, but its result is longer than the agent's CLI passes to its model (Cursor CLI: 40,000 bytes). Do not repeat an action for its result; ask for less: page_extractText with a smaller maxLength and its cursor, page_getPageInfo with a smaller maxPerKind, or a target
CANCELLED AgentSession The call was abandoned before the user answered its approval, so the request was taken down and a late answer does nothing
SKILL_UNKNOWN AgentSession The attached agent skill's id no longer resolves: the file moved, changed agents, or outgrew the size cap. Reopen the / picker and choose again

Scheduled tasks

Code Origin Meaning and next move
TASK_NOT_FOUND Daemon No task with that id. It was deleted from another browser or with browsentic tasks
TASK_LIMIT Daemon 25 tasks are already scheduled. Delete one first
REPLAY_UNAVAILABLE Extension The task's recording is gone, was never turned into steps, or needs a value the task does not hold

Agents

Code Origin Meaning and next move
AGENT_MISSING Runner The chosen agent's binary is not on the daemon's PATH. Set agents.<name>.bin to an absolute path
AGENT_NEEDS_PERMISSION Runner Antigravity has no rule allowing Browsentic's MCP tools (browsentic agent fix antigravity), Grok Build or Cursor CLI is not signed in (grok login, cursor-agent login), Qwen Code has no model provider configured (qwen, then /auth), or OpenCode 1 is signed in to no provider (opencode auth login), OpenCode 2 has no sign-in of Browsentic's own (the line the agent picker shows), or DeepSeek Harness is signed in to no DeepSeek account and no DEEPSEEK_API_KEY is set (dsh web)
AGENT_UNUSABLE Runner The CLI is present but cannot run, usually because it is too old for the flags Browsentic passes. Also a DeepSeek Harness older than 0.2.1, or one whose plugin tree leaves a tool on that Browsentic has not checked. On Windows, also a batch file that is not an npm or pnpm shim: set agents.<name>.bin to the program it runs. A run from an extension too old to know the chosen agent is refused the same way, with needs a newer Browsentic extension
AGENT_UNSAFE Runner The run was stopped before the agent could act on the machine: its plan had lost its containment, which is a bug in Browsentic, or the CLI itself said it had not applied it (Grok Build offering tools Browsentic never asks for, Qwen Code reporting a denied tool or a second MCP server as registered, OpenCode reporting that a tool outside the browser ran or opening a session in an agent other than Browsentic's, Codex running a shell command or changing a file with both switched off, Cursor CLI getting an answer from an MCP server the run denies, or DeepSeek Harness reporting that one of its own tools ran). Update both, and report it

Guardrails

Code Origin Meaning and next move
DECLINED Approval gate The user said no. Final: do not seek another route to the same effect
BLOCKED Policy A deny rule matched, or a confirm with nobody to answer it. The message names why. Guide
SITE_BLOCKED Extension The page is on the user's Blocked sites list, or the action would take the browser to a blocked site or ended up on one. Also returned for every page action while that list cannot be read. Final: do not retry or reach it another way; tell the user. Guide
SECRET_NOT_RELEASABLE Extension A sealed secret placeholder was passed somewhere it cannot be released. Only page_fillInput's value and page_typeText's text release one
SECRET_EXPIRED Extension That placeholder is no longer held: it aged out, or it was read in an earlier browser session. Read the value again
MAPPING_READ_ONLY Mapping gate A mapping run may only call the 14 read-only actions (plus page_clickElement when allowClicks is on)
MAPPING_OFF_SITE Mapping gate Navigation must be an absolute URL on the mapped origin, back and forward included
MAPPING_BUDGET Mapping gate The page or screenshot budget is spent
MAPPING_TAB_CHANGED Mapping gate The tab the run was pinned to is gone

Downloads

A capture refused with DOWNLOAD_OFF_SCOPE, DOWNLOAD_REFUSED or DOWNLOAD_TOO_LARGE also deletes the file the browser already wrote, so it leaves nothing behind to clean up. Those refusals are terminal for that file: retrying downloads it again and refuses it again.

Code Origin Meaning and next move
NO_DOWNLOAD_STARTED Extension The click produced no download. It probably opened a page instead: check where the tab landed, or pass the file's url directly
DOWNLOAD_FAILED Extension The browser stopped the transfer. The message carries its reason
DOWNLOADS_UNAVAILABLE Extension The loaded extension predates the downloads permission. Reload it and accept the prompt
DOWNLOAD_OFF_SCOPE Daemon The file came from a host this run was never pointed at. Ask the user, or start a run that names that site
DOWNLOAD_REFUSED Daemon An executable. Not overridable, by design
DOWNLOAD_TOO_LARGE Daemon Over 100 MB to capture, or over 25 MB to attach to a page
DOWNLOAD_NOT_FOUND Daemon No captured download with that id. Call page_listDownloads
DOWNLOAD_MISSING Daemon It was captured but is no longer on disk (swept, or deleted). Capture it again
DOWNLOAD_SAVE_FAILED Daemon The file could not be moved into the download folder. The message carries the reason

Attached files

These are not tool errors. They are the reason on a file analyst's report, shown on the file's chip and handed to the agent with the file so it can say why it cannot answer from it.

Code Verdict Meaning and next move
UNSUPPORTED_TYPE rejected Not text, a PDF or an image (an archive, an Office file, a program), or a PDF or image the active agent cannot open. The message names the agents that can
FILE_TOO_LARGE rejected Over 10 MB, or over its kind's limit: text 5 MB, PDF 10 MB, image 5 MB
EMPTY rejected The file has no bytes
UNREADABLE rejected The analyst opened it and could not read it: encrypted, password-protected or corrupted
TIMEOUT failed The analyst took longer than 60 seconds. Retry on the chip reads it again
CANCELLED failed The file was removed, its conversation ended, or the browser disconnected while it was being read
FILE_NOT_FOUND failed The browser no longer holds the file's bytes. Attach it again
AGENT_FAILED failed The agent could not start, or returned something that was not a report. The message says which

Android phones

These come from a conversation on the phone tab. The readiness codes (ADB_MISSING, NO_DEVICE, DEVICE_UNAUTHORIZED and the rest) are what browsentic android and the apps report; each has a row in troubleshooting.

Code Origin Meaning and next move
NOT_ON_PHONE Daemon or extension The tool works only in desktop tabs. A phone run is not offered it, so only an MCP client or a stale skill reaches this. Do that step in a desktop tab
PHONE_GONE Extension The phone session ended: the phone was unplugged, Chrome closed on it, Android was switched off, or the Bridge went away. Retrying will not help; reconnect from the phone tab
PHONE_PAGE_UNREACHABLE Extension The page on the phone was loading, or kept navigating, so its script world could not be made. Try again once it has loaded
TAP_MISSED Extension The point was outside the visible part of the phone's screen, so nothing was touched. Scroll it into view first
NAVIGATION_FAILED Extension Chrome on the phone could not open the address; the message carries Chrome's reason
CHROME_NOT_RUNNING Daemon Chrome is not open on the phone, so the session could not start. Open it, or run browsentic android open
NOT_OWNER Daemon Another paired browser is already driving this phone. One browser drives a phone at a time
NOT_CHECKED Daemon The control socket's android op was asked with peek before any browser or app was watching for phones, so the Bridge has not looked yet. browsentic status shows it as not checked; browsentic android looks
CDP_ERROR Daemon Chrome on the phone refused a command. The message carries Chrome's reason

See also