Skip to content

errors and logging

Dr K edited this page Nov 14, 2026 · 3 revisions

Errors and logging

A failure reaches three readers: a model that decides what to do next, a workflow that decides whether to retry, and an operator who reads the log. This area says what each failure means, how it is worded for each reader, and what the server writes down about it. It also holds the log's format, the loggers held at a level on purpose, and the one list of what is never logged.

Use cases

  • A model reads the host nonexistent.invalid, or a host it redirected to, did not resolve: check the URL, corrects the URL and goes on.
  • A workflow with retry-on-failure replays a 503 and stops at a 400.
  • An operator sets log_level to DEBUG and no secret, cookie or typed text appears.

Neighbours

ERR-1. This area owns the causes, their statuses, the wording and the log. Elsewhere: the reopen note in workspaces-and-sessions.md (WS-23), the page note in capture.md, the scrub in secrets-and-scope.md, the log lines for a refused credential in auth-and-roles.md (AUTH-49) and for the live view in live-view-and-control.md (LIVE-39, LIVE-40), the settings in config.md, the MCP errors in protocol.md and the surfaces' statuses in surfaces.md (SURF-40 to SURF-42). The exact shapes are in tests/golden/errors.json: one entry per cause, with its status and body.

What a failure means

ERR-2. A failure means one of five things to a caller, and the status carries it:

Class Meaning A client should
4xx The request is wrong and the same request fails again Stop, and change the request
404 The browser or thing named is gone Call open_session, or stop naming it
409 A person holds the browser Call await_control, then send the same request
503 The Grid cannot serve it now Retry after a wait
500 The server does not recognise it Report it

ERR-3. errors.status_for decides every status, for both surfaces. Its order is: Controlled (409), the gone causes and NotFound (404), TooLarge (413), NodeRefused, a Grid HTTP error, the unavailable causes (503), the caller's causes (400), any ValueError or TypeError (400), and anything else 500. TooLarge is a ValueError and is tested before that catch-all, so it is a 413 and not a 400. NoSession is a ValueError and is a 400.

ERR-4. The default is 500. Calling a failure the server does not recognise the caller's would stop a client from retrying something that may be the server's.

ERR-5. The package's own failures, in faults.py unless a column says otherwise:

Type Means Status
AssertionFailed An assert step's script came back false. Carries the author's message 400
NotFound The thing named is not there (a LookupError) 404
Controlled A person holds this browser (ERR-15) 409
NoSession The workspace has no browser open (a ValueError) 400
TooLarge A body or document over its cap (a ValueError) 413
Unresolved The page's host has no address 400
Untrusted The browser does not trust the page's certificate 400
ScriptTimedOut A script ran past the session's script timeout 400
NodeLost The Grid node holding the browser stopped answering mid-call 404
ScrubFailed A result could not be checked for secrets, so it is not returned 500
BidiUnavailable The browser answers WebDriver and its BiDi socket does not 503
SocketClosed A socket to the Grid closed, or never opened 503
NoNodeTook No node took a new browser before the Grid's queue gave up 503
NodeRefused A node took the request and could not start the browser 400 when the open asked for a raw capability or a version the caller chose, else 503
Ended (core/cancel.py) end_browser ran while this call drove the browser 404

ERR-6. The other failures the server raises are ValueErrors and so 400s: an invalid workspace, flow or Grid-session name, a flow that cannot be saved (every reason is listed), a run that cannot start, a secret binding the server will not perform, and a tool called without what it needs. A step that fails inside a run is reported by the run, not raised (FLOW-32 to FLOW-38).

ERR-7. A failure from the browser or the Grid is classified by its Selenium or HTTP class:

Status Classes
404 InvalidSessionIdException, NoSuchDriverException; a Grid HTTP 404
503 SessionNotCreatedException the Grid raised itself, requests.ConnectionError, requests.Timeout, any urllib3 error; a Grid 5xx or a Grid HTTP error with no response
400 TimeoutException, InvalidSelectorException, NoSuchElementException, NoSuchFrameException, NoAlertPresentException, InvalidArgumentException, JavascriptException, ElementNotInteractableException, ElementClickInterceptedException, MoveTargetOutOfBoundsException, StaleElementReferenceException, InsecureCertificateException; any other Grid 4xx
500 WebDriverException and everything else, including a BiDi error nothing caught

ERR-8. A timeout is a 400 because every wait in the server is for an element, a frame or a dialog the caller named, and the retry waits for the same thing. A slow Grid is a connection error, which is 503. Both transport libraries are classified, because an unreachable Grid is a urllib3 error to the Selenium driver and a requests error to the server's own Grid calls.

ERR-9. A browser that died under a call is recognised from the driver's own text, not from a probe, because a liveness check just after a crash can still say alive. The hub's reply for a silent node and Chrome's two crash messages make NodeLost. A host with no DNS address, in Chrome's or Firefox's words, makes Unresolved. No other connection failure is guessed to be the caller's.

ERR-10. Cancelled (a call whose caller stopped waiting) and StoreConflict (a Redis update that kept losing to other writers) have no mapping in status_for and would answer 500. StoreUnavailable and ConfigError stop the server at boot (CFG-32, CFG-34).

Where a failure is answered

ERR-11. Over HTTP a failure is {"error": <text>} with the status (SURF-42). The admin API answers the same way and logs every status at INFO. A filesystem error there answers its strerror and type, never the path.

ERR-12. The three signed-link file routes answer with no exception text, because a link is shareable. See AUTH-28.

ERR-13. Over MCP a failed tool call is a tool error whose text is Error calling tool '<name>': <message>, and a failed resource read Error reading resource '<uri>': <message>. A read that failed with a 404 cause is the MCP error -32002, any other 4xx -32602, and the rest an internal error (SURF-21). A call refused for its arguments is answered <tool> refused its arguments: <problem> without the prefix, and a failure FastMCP raised itself passes through unchanged.

How a failure is worded

ERR-14. faults.message makes the one sentence every surface and the log use. It takes the cause's first line, drops Selenium's Message: prefix, its Stacktrace: and a driver's (Session info: ...) line, and never returns an empty string: with no text it returns the class name. The documentation pointer Selenium appends on the same line stays.

ERR-15. A refusal for a person holding the browser names who and since when, and says to call await_control (LIVE-24 has the two sentences, for held and for requested).

ERR-16. Two notes may follow the sentence after a space, in this order: the reopen note (The browser was replaced before this call: ..., WS-23) and the page note (This call caused <n> page error(s) and <m> failed request(s): read <resource>.). No other note on an exception is ever said, because the others belong to a library.

ERR-17. The sentences the server fixes, one per cause. ERR-18 is the rule they follow:

Failure Sentence
NoSession no session is open in workspace '<name>' yet: call open_session first. It takes the window size and timeouts this session should use, which is why it is not done implicitly.
Unresolved the host <host>, or a host it redirected to, did not resolve: check the URL
Untrusted the site's certificate is not trusted: for a site with a self-signed certificate, open_session(insecure=true); an insecure browser gets no saved site data
ScriptTimedOut the script ran past this session's script timeout of <n>s: make it shorter, or raise it with open_session(script_timeout=<seconds>)
NodeLost the browser's Grid node stopped answering during this call (it may have crashed or run out of memory): call open_session for a new browser, which goes back to the page this one was on
Ended the browser was ended while this call was waiting
ScrubFailed this call's result could not be checked for secrets, so it is not returned. The action itself may have run: read the page before you repeat it.
BidiUnavailable the browser's BiDi channel did not answer: retry, and if it persists the Grid's /se/bidi route is down, or the open's and the save's variants of it

The ScriptTimedOut sentence leaves out of <n>s when the timeout cannot be read.

ERR-18. A failure the caller can fix names the fix: a tool to call, an option to pass, an input to check, or a retry. Unresolved names the host and allows that a redirect target failed, because the browser does not say which lookup failed. A failure the caller cannot fix says only what failed.

ERR-19. A failure text never contains:

  • a URL's userinfo, wherever the URL came from: the Grid's, the caller's page or a requested URI. A Grid HTTP refusal is cut to its status and reason, such as 404 Client Error: Not Found;
  • the browser's own text for an unresolved host or an untrusted certificate, which quotes the URL;
  • a Grid node's address or a Grid session id, which the hub's text carries, so NodeLost is a fixed sentence with no arguments;
  • a socket's URL: SocketClosed carries a code and the closing side's reason, or the failure's type when the socket never opened;
  • a path under the data directory, which a response reports by type;
  • a secret's value (ERR-20);
  • a stack trace.

ERR-20. A failure is scrubbed for secrets before it leaves the server, in place and with its type kept, so the status does not change. If the scrub itself fails, the answer is ScrubFailed, which fails closed and is logged by type alone.

What a result carries when part of a call worked

ERR-21. A failure is not a result, and a result may say that part of its work did not happen. Where a result can carry both, the part that worked is returned and the part that did not is named:

Call Field Says
screenshot file_error The capture is returned and the file was not kept, with the reason
open_session recording_error The browser is open and its recording cannot be filed
save_site_data skipped Which origins or storage were left out, and why
await_control page_error The hand-back is said and the page after it could not be read, in a failed call's words
run_flow A step's ok: false and error A step failed and the run's status says whether it stopped

ERR-22. A failed print is the exception to ERR-21: when the file cannot be kept the call fails with the print could not be kept (<type>), a 500, and the detail goes to the log.

ERR-23. A call that fails after a reopen, or with capture on, says what the failure left behind in the notes of ERR-16.

Logging

ERR-24. Logging is configured once, by main, after the settings load and before the server is built, so an error while building is logged. The root level is log_level (DEBUG, INFO, WARNING, ERROR or CRITICAL, default INFO, case-insensitive). Nothing is configured when the settings fail to load (CFG-32).

ERR-25. The format is the standard library's default for a root handler: LEVEL:logger:message, to stderr, with no timestamp and no colour. The log collector adds the time. The server's own loggers and FastMCP's go through that one handler. uvicorn's access and error loggers keep uvicorn's own handlers, and the server only adds a filter to them (ERR-29).

ERR-26. The server writes one line for one event and wraps nothing, because a log store keeps each physical line as an entry and a wrapped line would match only by its first fragment. A traceback is multi-line and its first line says what failed. A message that lists problems keeps its list lines.

ERR-27. FastMCP configures its own logger at import with Rich handlers that wrap at 80 columns without a terminal. The server removes them and lets the logger propagate to the root. Its level is the higher of INFO and the root's, because at DEBUG FastMCP logs every tool's arguments: script text, typed text and uploaded content. log_level: WARNING still quiets it.

ERR-28. Selenium's websocket_connection and remote_connection loggers are held at the higher of INFO and the root's level, because they log every BiDi frame and command body at DEBUG, and the frames of site data carry cookie values.

ERR-29. The access log names each request by its route template, so a workspace name in a path, a ?workspace= query and a signed link's signature never reach it. A path no route serves keeps its first segment only. The WebSocket lines on uvicorn.error are rewritten the same way. Method and status stay.

ERR-30. What is logged at each level:

Level What
ERROR A failure the server does not recognise (a 500) with a traceback; a call FastMCP failed with a cause that is not a caller's mistake, with a traceback; a print that could not be kept
WARNING A 503 over HTTP with its message; a caller's mistake over MCP as one line; the two boot warnings (OIDC with no roles, a reachable server with no token); a refused secret binding, a secret that cannot be read or checked, by type; flows, prompts, agents and skills that are skipped; recording and capture trouble by type; a refused live view
INFO The config= line and one line for each part that starts (the store, flows, secrets, recordings); a refused HTTP request (4xx) as <what> refused (<status>): <text>; a refused JWT; a bound secret by name, key, origin and tool; a saved flow, a failed step, a kept file; a browser ended; the live view's audit lines
DEBUG Detail nobody needs in the field: a recalled browser, a pointer that could not be read, a progress notification that was not sent

ERR-31. The status decides the level, by errors.status_for. A 4xx is the caller's and is not an incident, so a mistyped selector is one INFO line over HTTP and one WARNING line with the message over MCP, with no traceback. Over HTTP a 503 is one WARNING line and a 500 an ERROR with a traceback. Over MCP every 5xx, a 503 included, is an ERROR with a traceback, because FastMCP writes the line before any middleware runs and a filter on its logger rewrites only the 4xx.

ERR-32. A traceback is written through faults.formatted, which strips every URL's userinfo, because the frames quote the Grid URL.

ERR-33. The config= line names the file (or none), the Grid URL without userinfo, and auth, oidc, workspaces, skill, flows, secrets and recordings as on, off or a kind. It carries no token and no secret.

ERR-34. A refused caller is one line and no more. A JWT the verifier refuses is JWT refused for sub <sub>: <reason> at INFO (AUTH-49), and a live view socket refused is a WARNING (AUTH-32, LIVE-40). A wrong or missing server token is answered 401 unauthorized and writes no line beyond the access line.

What is never logged

ERR-35. One list, which every area's lines keep to:

Never Where the rule is held
A secret's value; a failure that might carry one is logged by its type alone workspace.scrub, SEC
A cookie's value, a BiDi frame, a command body ERR-28, SITE-9
A tool's arguments: script text, typed text, an upload's content ERR-27
A token, or a JWT claim other than sub AUTH-49
A URL's userinfo, the Grid's included ERR-32, ERR-33
A Grid session id, from the monitor, the call bracket and the workspaces WS-33
A query string, a workspace name in a path or a link's signature, in the access log ERR-29
The VNC password, a keystroke, a frame, pasted text (a count is logged), a page's URL or title LIVE-39, LIVE-40

Clone this wiki locally