SeleniumHQ/selenium · error · WebDriverException

timeout must be a positive number

Error message

timeout must be a positive number

What it means

Raised by WebSocketConnection.__init__ when the timeout argument is not an int/float or is negative. The constructor builds the BiDi/CDP websocket channel and needs a valid wait timeout. Note a real bug on the next line: the interval validation checks `timeout < 0` again instead of `interval < 0`, so a negative interval is not caught by its own guard (it can still slip through), and the message says 'positive' while the code actually allows 0.

Source

Thrown at py/selenium/webdriver/remote/websocket_connection.py:86

                    for pf in dataclasses.fields(value):
                        pv = getattr(value, pf.name)
                        if pv is not None:
                            result[_snake_to_camel(pf.name)] = self._convert(pv)
                else:
                    result[camel_key] = self._convert(value)
            return result
        return super().default(o)


logger = logging.getLogger(__name__)


class WebSocketConnection:
    _max_log_message_size = 9999

    def __init__(self, url, timeout, interval):
        if not isinstance(timeout, (int, float)) or timeout < 0:
            raise WebDriverException("timeout must be a positive number")
        if not isinstance(interval, (int, float)) or timeout < 0:
            raise WebDriverException("interval must be a positive number")

        self.url = url
        self.response_wait_timeout = timeout
        self.response_wait_interval = interval

        self.callbacks = {}
        self.session_id = None
        self._id = 0
        self._id_lock = threading.Lock()
        self._messages = {}
        self._started = False

        self._start_ws()
        self._wait_until(lambda: self._started)

    def close(self):

View on GitHub (pinned to aa36b38e69)

Solutions

1. Ensure client_config.websocket_timeout and websocket_interval are positive numbers (e.g. 60 and 0.1).
2. If constructing WebSocketConnection directly, pass numeric non-negative values for timeout and interval.
3. File/fix the upstream bug: the interval guard should check `interval < 0`, not `timeout < 0`.

Example fix

# before
conn = WebSocketConnection(url, timeout=-1, interval=0.1)  # raises

# after
conn = WebSocketConnection(url, timeout=60, interval=0.1)

if not isinstance(timeout, (int, float)) or timeout < 0:
    raise ValueError('timeout must be a non-negative number')
if not isinstance(interval, (int, float)) or interval < 0:
    raise ValueError('interval must be a non-negative number')
conn = WebSocketConnection(url, timeout, interval)

def is_valid_ws_timeout(v) -> bool:
    return isinstance(v, (int, float)) and v >= 0

from selenium.common.exceptions import WebDriverException
try:
    conn = WebSocketConnection(url, timeout, interval)
except WebDriverException:
    conn = WebSocketConnection(url, 60, 0.1)  # safe defaults

When it happens

Trigger: Constructing WebSocketConnection(url, timeout, interval) with timeout=None, a string, or a negative number. In practice this is triggered indirectly via driver.script/network (which pass command_executor.client_config.websocket_timeout) when that config value is misconfigured.

Common situations: A custom client_config with websocket_timeout set to None or a negative value, or a subclass that overrides the config. The direct constructor is rarely called by users.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• BiDi connection is closed
• BiDi connection is not open
• interval must be a positive number
• Timed out waiting for response to BiDi command {current_id}
• #{message['error']}: #{message['message']} #{message['stackt

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/c7ae0fb19f91ddb0. Report an issue: GitHub.