SeleniumHQ/selenium · error · WebDriverException

interval must be a positive number

Error message

interval must be a positive number

What it means

Raised by WebSocketConnection.__init__ while validating the polling interval used to wait for BiDi command responses. IMPORTANT BUG: the second guard re-checks `timeout < 0` instead of `interval < 0`, so the text 'interval must be a positive number' is misleading. In practice it fires when `interval` is not an int/float, or (due to the bug) when `timeout` is negative even though `interval` is valid. A genuinely negative `interval` currently does NOT raise.

Source

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

                        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):
        # Close the socket first so ``run_forever`` returns; only then join the
        # thread. Joining first would block for the full ``response_wait_timeout``

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass `interval` as a positive int or float (seconds), distinct from `timeout`.
2. Ensure `timeout` is also non-negative, since the buggy guard will surface the interval error for a negative timeout.
3. File/track the upstream defect: the interval guard must read `interval < 0`, not `timeout < 0`.

Example fix

# before
WebSocketConnection(url, timeout=10, interval="0.5")

# after
WebSocketConnection(url, timeout=10, interval=0.5)

def valid_interval(v) -> bool:
    return isinstance(v, (int, float)) and not isinstance(v, bool) and v > 0

# also ensure timeout >= 0 to avoid the misreported message
assert valid_interval(interval) and (isinstance(timeout, (int, float)) and timeout >= 0)

def is_positive_number(v) -> bool:
    return isinstance(v, (int, float)) and not isinstance(v, bool) and v > 0

When it happens

Trigger: 1) Constructing WebSocketConnection with a non-numeric interval (string, None, or a timedelta object). 2) Passing a negative `timeout` together with a valid `interval` - the buggy condition (`timeout < 0`) triggers and reports the wrong field.

Common situations: Defaulting interval from an unset config value (None); passing a timedelta instead of a raw float; reusing the timeout literal for both args. The misleading message routinely sends developers to debug the interval value when timeout is the real culprit.

Related errors

• Event '{event}' not found. Available events: {self._availabl
• {self._label.capitalize()} '{handler_id}' not found
• Extra header '{name}' not found
• Unsupported DOM mutation type(s) {sorted(unknown)}; expected
• mutation_types must name at least one mutation type

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