Exceptions

Pydoll 抛出的异常，例如 ElementNotFound 和 WaitElementTimeout。详见 查找元素。

pydoll.exceptions

Pydoll Exception Classes

This module contains all exception classes used throughout the Pydoll library, organized into logical categories based on their function and usage patterns. Each category uses a base class to provide common functionality for related exceptions.

PydollException

PydollException(message='')

Bases: Exception

Base class for all Pydoll exceptions.

message class-attribute instance-attribute

message = message or self.message

ConnectionException

ConnectionException(message='')

Bases: PydollException

Base class for exceptions related to browser connection.

message class-attribute instance-attribute

message = 'A connection error occurred'

ConnectionFailed

ConnectionFailed(message='')

Bases: ConnectionException

Raised when connection to the browser cannot be established.

message class-attribute instance-attribute

message = 'Failed to connect to the browser'

ReconnectionFailed

ReconnectionFailed(message='')

Bases: ConnectionException

Raised when an attempt to reconnect to the browser fails.

message class-attribute instance-attribute

message = 'Failed to reconnect to the browser'

WebSocketConnectionClosed

WebSocketConnectionClosed(message='')

Bases: ConnectionException

Raised when the WebSocket connection to the browser is closed unexpectedly.

message class-attribute instance-attribute

message = 'The WebSocket connection is closed'

NetworkError

NetworkError(message='')

Bases: ConnectionException

Raised when a general network error occurs during browser communication.

message class-attribute instance-attribute

message = 'A network error occurred'

BrowserException

BrowserException(message='')

Bases: PydollException

Base class for exceptions related to browser process management.

message class-attribute instance-attribute

message = 'A browser error occurred'

BrowserNotRunning

BrowserNotRunning(message='')

Bases: BrowserException

Raised when attempting to interact with a browser that is not running.

message class-attribute instance-attribute

message = 'The browser is not running'

FailedToStartBrowser

FailedToStartBrowser(message='')

Bases: BrowserException

Raised when the browser process cannot be started.

message class-attribute instance-attribute

message = 'Failed to start the browser'

UnsupportedOS

UnsupportedOS(message='')

Bases: BrowserException

Raised when attempting to run on an unsupported operating system.

message class-attribute instance-attribute

message = 'Unsupported OS'

NoValidTabFound

NoValidTabFound(message='')

Bases: BrowserException

Raised when no valid browser tab can be found or created.

message class-attribute instance-attribute

message = 'No valid attached tab found'

InvalidConnectionPort

InvalidConnectionPort(message='')

Bases: BrowserException

Raised when an invalid (non-positive) connection port is provided.

message class-attribute instance-attribute

message = 'Connection port must be a positive integer'

InvalidWebSocketAddress

InvalidWebSocketAddress(message='')

Bases: BrowserException

Raised when an invalid WebSocket address is provided or required but missing.

message class-attribute instance-attribute

message = 'Invalid WebSocket address'

MissingTargetOrWebSocket

MissingTargetOrWebSocket(message='')

Bases: BrowserException

Raised when a Tab has neither target ID nor WebSocket address available.

message class-attribute instance-attribute

message = 'Tab has no target ID or WebSocket address'

FingerprintContextConflict

FingerprintContextConflict(message='')

Bases: BrowserException

Raised when a different fingerprint is applied within one browser context.

Service and shared workers are shared across all tabs of a browser context, so a single context can only carry one fingerprint identity. Use a separate browser context per identity (Browser.create_browser_context() + Browser.new_tab(browser_context_id=...)).

message class-attribute instance-attribute

message = 'A different fingerprint is already applied to this browser context. Multiple fingerprints are only supported across separate browser contexts: create one context per identity via Browser.create_browser_context() and open each tab with new_tab(browser_context_id=...).'

ProtocolException

ProtocolException(message='')

Bases: PydollException

Base class for exceptions related to CDP protocol communication.

message class-attribute instance-attribute

message = 'A protocol error occurred'

TopLevelTargetRequired

TopLevelTargetRequired(message='')

Bases: ProtocolException

Raised when a command can only be executed on top-level targets.

message class-attribute instance-attribute

message = 'Command can only be executed on top-level targets.'

InvalidCommand

InvalidCommand(message='')

Bases: ProtocolException

Raised when an invalid command is sent to the browser.

message class-attribute instance-attribute

message = 'The command provided is invalid'

InvalidResponse

InvalidResponse(message='')

Bases: ProtocolException

Raised when an invalid response is received from the browser.

message class-attribute instance-attribute

message = 'The response received is invalid'

ResendCommandFailed

ResendCommandFailed(message='')

Bases: ProtocolException

Raised when an attempt to resend a failed command fails.

message class-attribute instance-attribute

message = 'Failed to resend the command'

CommandExecutionTimeout

CommandExecutionTimeout(message='')

Bases: ProtocolException

Raised when a command execution times out.

message class-attribute instance-attribute

message = 'The command execution timed out'

CommandFailed

CommandFailed(method='', code=0, message='', data='')

Bases: ProtocolException

Raised when the browser answers a command with a CDP error instead of a result.

Covers protocol-level rejections (unknown method, invalid params, session not found) and domain-level failures such as an object id that no longer resolves or an execution context destroyed by a navigation.

ATTRIBUTE	DESCRIPTION
method	CDP method that was rejected.
code	JSON-RPC style error code reported by the browser.
data	Optional extra detail the browser attached to the error.

message class-attribute instance-attribute

message = 'The browser rejected the command'

method instance-attribute

method = method

code instance-attribute

code = code

data instance-attribute

data = data

InvalidCallback

InvalidCallback(message='')

Bases: ProtocolException

Raised when an invalid callback is provided for an event.

message class-attribute instance-attribute

message = 'The callback provided is invalid'

EventNotSupported

EventNotSupported(message='')

Bases: ProtocolException

Raised when an attempt is made to subscribe to an unsupported event.

message class-attribute instance-attribute

message = 'The event is not supported'

ElementException

ElementException(message='')

Bases: PydollException

Base class for exceptions related to element interactions.

message class-attribute instance-attribute

message = 'An element interaction error occurred'

ElementNotFound

ElementNotFound(message='')

Bases: ElementException

Raised when an element cannot be found in the DOM.

message class-attribute instance-attribute

message = 'The specified element was not found'

ElementNotVisible

ElementNotVisible(message='')

Bases: ElementException

Raised when attempting to interact with an element that is not visible.

message class-attribute instance-attribute

message = 'The element is not visible'

ElementNotInteractable

ElementNotInteractable(message='')

Bases: ElementException

Raised when attempting to interact with an element that cannot receive interaction.

message class-attribute instance-attribute

message = 'The element is not interactable'

ClickIntercepted

ClickIntercepted(message='')

Bases: ElementException

Raised when a click operation is intercepted by another element.

message class-attribute instance-attribute

message = 'The click was intercepted'

ElementNotAFileInput

ElementNotAFileInput(message='')

Bases: ElementException

Raised when attempting to use file input methods on a non-file input element.

message class-attribute instance-attribute

message = 'The element is not a file input'

ShadowRootNotFound

ShadowRootNotFound(message='')

Bases: ElementException

Raised when an element does not have an attached shadow root.

message class-attribute instance-attribute

message = 'No shadow root attached to this element'

TimeoutException

TimeoutException(message='')

Bases: PydollException

Base class for exceptions related to timeouts.

message class-attribute instance-attribute

message = 'A timeout occurred'

PageLoadTimeout

PageLoadTimeout(message='')

Bases: TimeoutException

Raised when a page load operation times out.

message class-attribute instance-attribute

message = 'Page load timed out'

WaitElementTimeout

WaitElementTimeout(message='')

Bases: TimeoutException

Raised when waiting for an element times out.

message class-attribute instance-attribute

message = 'Timed out waiting for element to appear'

DownloadTimeout

DownloadTimeout(message='')

Bases: TimeoutException

Raised when waiting for a file download to complete times out.

message class-attribute instance-attribute

message = 'Timed out waiting for download to complete'

NavigationError

NavigationError(url, error_text)

Bases: PydollException

Raised when page navigation fails (e.g., DNS resolution failure).

url instance-attribute

url = url

error_text instance-attribute

error_text = error_text

message class-attribute instance-attribute

message = message or self.message

ConfigurationException

ConfigurationException(message='')

Bases: PydollException

Base class for exceptions related to configuration and options.

message class-attribute instance-attribute

message = 'A configuration error occurred'

InvalidOptionsObject

InvalidOptionsObject(message='')

Bases: ConfigurationException

Raised when an invalid options object is provided.

message class-attribute instance-attribute

message = 'The options object provided is invalid'

InvalidBrowserPath

InvalidBrowserPath(message='')

Bases: ConfigurationException

Raised when an invalid browser executable path is provided.

message class-attribute instance-attribute

message = 'The browser path provided is invalid'

ArgumentAlreadyExistsInOptions

ArgumentAlreadyExistsInOptions(message='')

Bases: ConfigurationException

Raised when attempting to add a duplicate argument to browser options.

message class-attribute instance-attribute

message = 'The argument already exists in the options'

ArgumentNotFoundInOptions

ArgumentNotFoundInOptions(message='')

Bases: ConfigurationException

Raised when attempting to remove an argument that does not exist in browser options.

message class-attribute instance-attribute

message = 'The argument does not exist in the options'

InvalidFileExtension

InvalidFileExtension(message='')

Bases: ConfigurationException

Raised when an unsupported file extension is provided.

message class-attribute instance-attribute

message = 'The file extension provided is not supported'

InvalidTabInitialization

InvalidTabInitialization(message='')

Bases: ConfigurationException

Raised when creating a Tab without connection_port, target_id or ws_address.

message class-attribute instance-attribute

message = 'Either connection_port, target_id, or ws_address must be provided'

MissingScreenshotPath

MissingScreenshotPath(message='')

Bases: ConfigurationException

Raised when take_screenshot is called without path and not returning base64.

message class-attribute instance-attribute

message = 'path is required when as_base64 is False'

DialogException

DialogException(message='')

Bases: PydollException

Base class for exceptions related to browser dialogs.

message class-attribute instance-attribute

message = 'A dialog error occurred'

NoDialogPresent

NoDialogPresent(message='')

Bases: DialogException

Raised when attempting to interact with a dialog that doesn't exist.

message class-attribute instance-attribute

message = 'No dialog present on the page'

NotAnIFrame

NotAnIFrame(message='')

Bases: PydollException

Raised when an element is not an iframe.

message class-attribute instance-attribute

message = 'The element is not an iframe'

InvalidIFrame

InvalidIFrame(message='')

Bases: PydollException

Raised when an iframe is not valid.

message class-attribute instance-attribute

message = 'The iframe is not valid'

IFrameNotFound

IFrameNotFound(message='')

Bases: PydollException

Raised when an iframe is not found.

message class-attribute instance-attribute

message = 'The iframe was not found'

NetworkEventsNotEnabled

NetworkEventsNotEnabled(message='')

Bases: PydollException

Raised when network events are not enabled.

message class-attribute instance-attribute

message = 'Network events not enabled'

RequestException

RequestException(message='')

Bases: PydollException

Base class for exceptions related to HTTP requests.

message class-attribute instance-attribute

message = 'An HTTP request error occurred'

HTTPError

HTTPError(message='')

Bases: RequestException

Exception raised for HTTP error responses (4xx and 5xx status codes).

message class-attribute instance-attribute

message = 'An HTTP error occurred'

HarRecordingError

HarRecordingError(message='')

Bases: RequestException

Raised when HAR recording fails.

message class-attribute instance-attribute

message = 'HAR recording error occurred'

ScriptException

ScriptException(message='')

Bases: PydollException

Base class for exceptions related to JavaScript execution.

message class-attribute instance-attribute

message = 'A script execution error occurred'

InvalidScriptWithElement

InvalidScriptWithElement(message='')

Bases: ScriptException

Raised when a script contains 'argument' but no element is provided.

message class-attribute instance-attribute

message = 'Script contains "argument" but no element was provided'

WrongPrefsDict

WrongPrefsDict(message='')

Bases: PydollException

Raised when the prefs dict provided contains the 'prefs' key

message class-attribute instance-attribute

message = 'The dict can not contain "prefs" key, provide only the prefs options'

ElementPreconditionError

ElementPreconditionError(message='')

Bases: ElementException

Raised when invalid or missing preconditions are provided for element operations.

message class-attribute instance-attribute

message = 'Invalid element preconditions'