{"record":{"id":"14f29c8317ceb5ad","repo":"SeleniumHQ/selenium","slug":"this-function-requires-a-virtual-authenticator-to","errorCode":null,"errorMessage":"This function requires a virtual authenticator to be set.","messagePattern":"This function requires a virtual authenticator to be set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py/selenium/webdriver/common/virtual_authenticator.py","lineNumber":216,"sourceCode":"    @functools.wraps(func)\n    def wrapper(self, *args, **kwargs):\n        assert self.caps[\"browserName\"].lower() not in [\n            \"firefox\",\n            \"safari\",\n        ], \"This only currently works in Chromium based browsers\"\n        return func(self, *args, **kwargs)\n\n    return wrapper\n\n\ndef required_virtual_authenticator(func):\n    \"\"\"Decorator to ensure that the function is called with a virtual authenticator.\"\"\"\n\n    @functools.wraps(func)\n    @required_chromium_based_browser\n    def wrapper(self, *args, **kwargs):\n        if not self.virtual_authenticator_id:\n            raise ValueError(\"This function requires a virtual authenticator to be set.\")\n        return func(self, *args, **kwargs)\n\n    return wrapper\n","sourceCodeStart":198,"sourceCodeEnd":220,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/py/selenium/webdriver/common/virtual_authenticator.py#L198-L220","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call driver.add_virtual_authenticator(VirtualAuthenticatorOptions()) first and capture the returned id.","Guard WebAuthn calls by checking driver.virtual_authenticator_id is set before invoking credential methods.","Ensure you are on a Chromium-based browser (Chrome/Edge) — the decorator asserts this first.","Re-order setup so authenticator creation precedes any credential operations."],"exampleFix":"# before\nfrom selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions\ndriver.add_credential(...)  # -> ValueError\n\n# after\nfrom selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions, Credential\nauthenticator_id = driver.add_virtual_authenticator(VirtualAuthenticatorOptions(has_resident_key=True))\ndriver.add_credential(credential)","handlingStrategy":"validation","validationCode":"from selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions\nif not getattr(driver, 'virtual_authenticator_id', None):\n    driver.add_virtual_authenticator(VirtualAuthenticatorOptions(has_resident_key=True))","typeGuard":"def has_virtual_authenticator(driver) -> bool:\n    return bool(getattr(driver, 'virtual_authenticator_id', None))","tryCatchPattern":"try:\n    driver.add_credential(cred)\nexcept ValueError as e:\n    if 'requires a virtual authenticator' in str(e):\n        driver.add_virtual_authenticator(VirtualAuthenticatorOptions())\n        driver.add_credential(cred)","preventionTips":["Always call add_virtual_authenticator before any credential method.","Wrap WebAuthn setup in a helper that asserts the id is set.","Confirm the browser is Chromium-based before using virtual authenticators."],"tags":["virtual-authenticator","webauthn","ordering","chromium","valueerror"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}