Repository navigation
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.
- 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_leveltoDEBUGand no secret, cookie or typed text appears.
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.
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).
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.
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
NodeLostis a fixed sentence with no arguments; - a socket's URL:
SocketClosedcarries 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.
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.
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.
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 |
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network