SeleniumHQ/selenium · error · TypeError

missing 1 required keyword-only argument: 'options' (instanc

Error message

missing 1 required keyword-only argument: 'options' (instance of driver `options.Options` class)

What it means

Raised in `WebDriver.__init__` when `options` is None — the constructor requires a keyword-only `options` argument (an instance of a driver's `Options` class, or a list of Options). The class historically accepted no options, but the API now mandates one so capabilities are derived deterministically. It is a TypeError.

Source

Thrown at py/selenium/webdriver/remote/webdriver.py:261

        Args:
            command_executor: Either a string representing the URL of the remote
                server or a custom remote_connection.RemoteConnection object.
                Defaults to 'http://127.0.0.1:4444'.
            keep_alive: (Deprecated) Whether to configure
                remote_connection.RemoteConnection to use HTTP keep-alive.
                Defaults to True.
            file_detector: Pass a custom file detector object during
                instantiation. If None, the default LocalFileDetector() will be
                used.
            options: Instance of a driver options.Options class.
            locator_converter: Custom locator converter to use. Defaults to None.
            web_element_cls: Custom class to use for web elements. Defaults to
                WebElement.
            client_config: Custom client configuration to use. Defaults to None.
        """
        if options is None:
            raise TypeError(
                "missing 1 required keyword-only argument: 'options' (instance of driver `options.Options` class)"
            )
        elif isinstance(options, list):
            capabilities = create_matches(options)
            _ignore_local_proxy = False
        else:
            capabilities = options.to_capabilities()
            _ignore_local_proxy = options._ignore_local_proxy
        self.command_executor = command_executor
        if isinstance(self.command_executor, (str, bytes)):
            self.command_executor = get_remote_connection(
                capabilities,
                command_executor=command_executor,
                keep_alive=keep_alive,
                ignore_local_proxy=_ignore_local_proxy,
                client_config=client_config,
            )
        self._is_remote = True

View on GitHub (pinned to aa36b38e69)

Solutions

1. Construct and pass the right Options, e.g. webdriver.Remote(options=ChromeOptions()).
2. For multi-browser, pass a list: options=[ChromeOptions(), ...] (create_matches is applied).
3. Remove legacy desired_capabilities= usage and migrate to Options.

Example fix

# before
driver = webdriver.Remote(command_executor=URL)

# after
from selenium.webdriver.chrome.options import Options
opts = Options()
driver = webdriver.Remote(command_executor=URL, options=opts)

if options is None:
    raise TypeError('options is required; construct an Options instance for the target browser')

def has_options(options) -> bool:
    return options is not None and (hasattr(options, 'to_capabilities') or isinstance(options, list))

When it happens

Trigger: Instantiating `webdriver.Remote(...)` (or any driver) without passing options=, or passing options=None explicitly. Also using an old call style `webdriver.Remote(command_executor, desired_capabilities=...)` from pre-4.x tutorials.

Common situations: Upgrading from Selenium 3 to 4+ where options used to be optional; stale Stack Overflow examples; forgetting to import/construct the Options object for the target browser.

Related errors

• Params must be an instance of CookieFilter. Received:'${cook
• Invalid URL: ${aUrl}
• no capabilities provided for merge
• Capability keys must be strings: ${typeof key}
• Level must be >= 0

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