Skip to content

Errors

from nativehtmlkit import (NativeHTMLKitError, RpcError, RpcTimeoutError, HostDisconnectedError,
                           DisconnectedError, HostProtocolError, ProtocolError, StaleDocumentError,
                           StartupError)

Every SDK error derives from NativeHTMLKitError. Catch it to handle "anything NativeHTMLKit"; catch the subclasses to react precisely. Never parse str(error): use the attributes.

Hierarchy

NativeHTMLKitError (Exception)
├── RpcError                          code = numeric wire error code
│   └── ClientBusyError               local back-pressure, nothing sent       (nativehtmlkit.client)
├── RpcTimeoutError (TimeoutError)    local deadline expired, outcome unknown
├── HostDisconnectedError (ConnectionError)
│   └── DisconnectedError             connection lost or closed, outcome unknown
├── HostProtocolError
│   └── ProtocolError                 the host broke wire v1 (fatal)
├── LocalRequestError (ValueError)    request not encodable / > 2 MiB, nothing sent (nativehtmlkit.errors)
├── StaleHandleError                                                         (nativehtmlkit.errors)
│   ├── StaleDocumentError (RuntimeError)   window/document/node no longer live
│   └── ApplicationShutdownError (RuntimeError)   shutdown began, no new windows/documents
├── StartupError (RuntimeError)       host could not be started or reached
├── HostVerificationError (FileNotFoundError)   bundled host fails its SHA-256 pin (nativehtmlkit.errors)
└── UnsupportedFeatureError                                                  (nativehtmlkit.errors)

Classes without a module note are exported by nativehtmlkit. StaleDocumentError and ApplicationShutdownError share the base StaleHandleError; StartupError is in nativehtmlkit._bootstrap and re-exported.

Common attributes

Attribute Meaning
classification Stable category string, e.g. "NHK-HOST-RPC", "NHK-HANDLE-STALE"
code Same as classification, except on RpcError, where it is the numeric wire code
operation The RPC method involved, if any (e.g. "document.command")
request_id The SDK's wire request id, if any
session_id The diagnostics session id of this process
data Extra error data from the host (RpcError)
retryable False for all current classes
outcome_unknown True when the host may or may not have applied the operation (RpcTimeoutError, disconnects). The SDK never claims a rollback.
Class classification
RpcError NHK-HOST-RPC
ClientBusyError NHK-CLIENT-BUSY (code -32005, local=True)
RpcTimeoutError NHK-TRANSPORT-TIMEOUT
HostDisconnectedError, DisconnectedError NHK-HOST-DISCONNECTED (plus pending_failed: requests failed by the same event)
HostProtocolError, ProtocolError NHK-PROTOCOL-MALFORMED
LocalRequestError NHK-REQUEST-INVALID
StaleHandleError, StaleDocumentError NHK-HANDLE-STALE
ApplicationShutdownError NHK-APP-SHUTDOWN
StartupError NHK-STARTUP
HostVerificationError NHK-HOST-UNVERIFIED
UnsupportedFeatureError NHK-FEATURE-UNSUPPORTED

RpcError

RpcError(code, message, data=None, *, operation=None, request_id=None); members code (int), message (host text, for logs only), data, local (False for host errors) and error_id (same as classification). Wire codes:

Code Name Typical cause
-32600 invalid request malformed envelope
-32601 method not found unknown method
-32602 invalid params unknown element id, unknown member, bad argument
-32603 internal unexpected host failure
-32001 unsupported not available here: headless mode, no desktop service, platform policy (e.g. Wayland placement)
-32002 unavailable a service or file is missing at run time (e.g. load_file of a missing file)
-32003 denied policy refusal (e.g. open_external with an unsupported URI scheme)
-32004 closed window or document no longer exists in the host
-32005 busy a limit was reached (windows, 1 MiB HTML, bitmap budget, one dialog per window, pending requests)
-32006 cancelled request cancelled
-32007 disconnected
-32008 invalid state wrong lifecycle phase: app.ready without a window or most calls after shutdown began
-32009 timeout
-32010 version mismatch protocol version is not 1
-32011 unauthenticated wrong or missing launch token

Treat unknown codes as failures.

StaleDocumentError

Raised locally, before anything is sent, when you use a Window that is closed, or a Document/Node that was replaced, unloaded, closed or retired by shutdown. It is a RuntimeError. (If the host itself receives a stale id, it answers RpcError -32004 instead.)

Patterns

from nativehtmlkit import NativeHTMLKitError, RpcError, StaleDocumentError

try:
    window.document.set_text("status", "Saved")
except StaleDocumentError:
    pass                         # the window was closed meanwhile; nothing to update
except RpcError as error:
    if error.code == -32602:
        print("No element with that id")
    else:
        raise

In background threads that update the UI, catch NativeHTMLKitError around each update and stop the thread when it occurs: it covers stale handles, shutdown and disconnects.


Source: nativehtmlkit-python/docs/reference/errors.md · edit the page there.