halyard.HalyardError subclass,
importable from halyard. Branch on the class or on kind, never on the
message text. A few failures raise other exceptions; see
Not a HalyardError.
HalyardError
| Attribute | Type | Description |
|---|---|---|
kind | str | The DCP error kind, such as ActionTimeout. |
method | str | The DCP method that failed, such as Locator.click. |
code | int | None | The DCP error code, or the HTTP status for a session client error. |
retryable | bool | Whether sending the same call again can succeed. |
Subclasses
| Class | DCP kinds | Raised when |
|---|---|---|
TimeoutError | ActionTimeout, Timeout | An element never became actionable, a wait ran out, a locator matched several elements, or no reply came within the client’s wait (kind Timeout). Same name as Playwright’s. |
EvaluationError | none | A script passed to evaluate threw. stack holds its stack trace. |
InvalidArgsError | InvalidArgs | The arguments were rejected: a malformed selector, an unknown key, a refused chord, a script result over 1 MiB. Also HTTP 400 and 422. |
UnsupportedError | StrategyUnavailable, UnknownOp | The session doesn’t serve this method, option or strategy. |
NavigationError | NavigationFailed | Chrome couldn’t load the page. |
TargetNotFoundError | TargetNotFound | The tab doesn’t exist, or was closed. |
NotConnectedError | NotConnected, DeviceOffline, NoAllocation | The control socket couldn’t open (including a refused token or an ended session), closed while a call waited for its reply, or was already closed. |
UnauthorizedError | Unauthorized | The token or API key was refused. Also HTTP 401 and 403. |
ConflictError | Conflict | The request conflicts with the session’s state. Also HTTP 409. |
DialogOpenError | DialogOpen | A dialog held open by a page.on("dialog") listener blocks the page, and no listener answered it. |
StaleNodeError | StaleNode | A node reference from an earlier read is gone: a phone’s node_id, or a browser [ref=...] from aria_snapshot(refs=True). |
TreeUnavailableError | TreeUnavailable | The accessibility tree has nothing to read right now. Phones only. |
Phone-specific
These come up only on a phone:| Error | When |
|---|---|
StaleNodeError | A locator pinned with node_id, or accessibility.partial() or children(), names a node that has left the screen. Take a fresh accessibility.snapshot(). |
TreeUnavailableError | The accessibility tree is on but has no app window to read, such as while a system dialog is up. |
UnsupportedError for a strategy | A locator needs the accessibility tree (role, name, states, node_id, strategy="accessibility", wait_for(state="enabled"), accessible_name()) and the phone has none; or a selector kind or strategy the phone doesn’t serve, such as dom. halyard.phone.StrategyUnavailableError is another name for it. |
InvalidArgsError for a removed field | phone.locator() given id, value, window_id, android_class_name or package_name, or phone.get_by_id(). |
ValueError | A phone locator timeout outside 0 to 60,000 milliseconds, or a within() or has() locator that sets its own strategy, model or OCR engine. |
halyard.phone.ActionTimeoutError is another name for TimeoutError.
Computer-specific
| Error | When |
|---|---|
TargetNotFoundError | A file or folder doesn’t exist (files.read_text(), stat()). |
InvalidArgsError | A write under C:\ax other than C:\ax\downloads; a file over 32 MiB; reading a folder; ending a protected process; a resolution that isn’t a display mode. |
TimeoutError | windows.wait_for() ran out. A processes.run() that runs out does not raise: its result has timed_out set. |
Browser-specific
| Error | When |
|---|---|
DialogOpenError | A page.on("dialog") listener returned without calling accept() or dismiss(), so the dialog still blocks the page. |
InvalidArgsError | frame_locator() given a selector that isn’t CSS, or an element that isn’t an <iframe>; answering a dialog twice. |
NavigationError | download.save_as() or path() on a failed download. |
Other kinds
Any other DCP kind raisesHalyardError itself. So does any other HTTP error
status from the session client.
A reply that doesn’t arrive within the connection’s timeout (the timeout=
given to connect(), 60 seconds by default) raises TimeoutError with kind
Timeout. Calls given a longer timeout of their own wait that long, plus a
margin.
from halyard import TimeoutError shadows Python’s built-in TimeoutError, as
Playwright’s does.
Not a HalyardError
These come from Python or the libraries underneath, so catch them separately where they matter:| Exception | When |
|---|---|
httpx.HTTPError (such as httpx.ConnectError, httpx.TimeoutException) | The session client (Client) can’t reach the API or times out. An HTTP error status is a HalyardError. |
websockets.exceptions.ConnectionClosed | A browser or computer control socket closed and a new call is sent on it. A call already waiting for its reply raises NotConnectedError instead. |
ValueError | An argument checked before anything is sent: no API key or control URL, a screenshot type other than "png" or "jpeg", an upload payload without name or buffer. |
TypeError | set_input_files() given something that isn’t a path or a payload. |
OSError | A local file can’t be read or written (set_input_files(), save_as(), files.upload(), screenshot(path=...)). |
AssertionError | An expect() assertion still fails when its timeout runs out. |