SeleniumHQ/selenium · error · ValueError

This function requires a virtual authenticator to be set.

Error message

This function requires a virtual authenticator to be set.

What it means

Raised by the @required_virtual_authenticator decorator when a WebAuthn-related method is called on the WebDriver before a virtual authenticator has been registered via add_virtual_authenticator(). The decorator also first checks the browser is Chromium-based; only then does it assert that virtual_authenticator_id is set. This is a ValueError, not a WebDriverException.

Source

Thrown at py/selenium/webdriver/common/virtual_authenticator.py:216

    @functools.wraps(func)
    def wrapper(self, *args, **kwargs):
        assert self.caps["browserName"].lower() not in [
            "firefox",
            "safari",
        ], "This only currently works in Chromium based browsers"
        return func(self, *args, **kwargs)

    return wrapper


def required_virtual_authenticator(func):
    """Decorator to ensure that the function is called with a virtual authenticator."""

    @functools.wraps(func)
    @required_chromium_based_browser
    def wrapper(self, *args, **kwargs):
        if not self.virtual_authenticator_id:
            raise ValueError("This function requires a virtual authenticator to be set.")
        return func(self, *args, **kwargs)

    return wrapper

View on GitHub (pinned to aa36b38e69)

Solutions

1. Call driver.add_virtual_authenticator(VirtualAuthenticatorOptions()) first and capture the returned id.
2. Guard WebAuthn calls by checking driver.virtual_authenticator_id is set before invoking credential methods.
3. Ensure you are on a Chromium-based browser (Chrome/Edge) — the decorator asserts this first.
4. Re-order setup so authenticator creation precedes any credential operations.

Example fix

# before
from selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions
driver.add_credential(...)  # -> ValueError

# after
from selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions, Credential
authenticator_id = driver.add_virtual_authenticator(VirtualAuthenticatorOptions(has_resident_key=True))
driver.add_credential(credential)

from selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions
if not getattr(driver, 'virtual_authenticator_id', None):
    driver.add_virtual_authenticator(VirtualAuthenticatorOptions(has_resident_key=True))

def has_virtual_authenticator(driver) -> bool:
    return bool(getattr(driver, 'virtual_authenticator_id', None))

try:
    driver.add_credential(cred)
except ValueError as e:
    if 'requires a virtual authenticator' in str(e):
        driver.add_virtual_authenticator(VirtualAuthenticatorOptions())
        driver.add_credential(cred)

When it happens

Trigger: Calling driver.add_credential(...), driver.get_credentials(), driver.remove_credential(...), or driver.remove_all_credentials() before calling driver.add_virtual_authenticator(options). The virtual_authenticator_id attribute is falsy until the authenticator is added via the BiDi/WebDriver command.

Common situations: Adapting an older example that assumed an authenticator existed by default, reordering test setup so credential creation runs before authenticator creation, or copy-pasting WebAuthn snippet without the add_virtual_authenticator step.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• This function requires a virtual authenticator to be set.
• Binary Location Must be a String
• Path to the extension doesn't exist
• argument can not be null
• service_args must be a sequence

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