SeleniumHQ/selenium · error · WebDriverException

You must enable downloads in order to work with downloadable

Error message

You must enable downloads in order to work with downloadable files.

What it means

Raised by get_downloadable_files() when 'se:downloadsEnabled' is not present in the session capabilities. Selenium's downloadable-files feature requires the server to opt in at session creation (it must hold files server-side), so the client gates every download API on this capability flag. Without it, the call is meaningless.

Source

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

    def set_user_verified(self, verified: bool) -> None:
        """Set whether the authenticator will simulate success or failure on user verification.

        Args:
            verified: True if the authenticator will pass user verification,
                False otherwise.

        Example:
            `driver.set_user_verified(True)`
        """
        self.execute(
            Command.SET_USER_VERIFIED,
            {"authenticatorId": self._authenticator_id, "isUserVerified": verified},
        )

    def get_downloadable_files(self) -> list:
        """Retrieves the downloadable files as a list of file names."""
        if "se:downloadsEnabled" not in self.capabilities:
            raise WebDriverException("You must enable downloads in order to work with downloadable files.")

        return self.execute(Command.GET_DOWNLOADABLE_FILES)["value"]["names"]

    def download_file(self, file_name: str, target_directory: str) -> None:
        """Download a file with the specified file name to the target directory.

        Args:
            file_name: The name of the file to download.
            target_directory: The path to the directory to save the downloaded file.

        Example:
            `driver.download_file("example.zip", "/path/to/directory")`
        """
        if "se:downloadsEnabled" not in self.capabilities:
            raise WebDriverException("You must enable downloads in order to work with downloadable files.")

        if not os.path.exists(target_directory):
            os.makedirs(target_directory)

View on GitHub (pinned to aa36b38e69)

Solutions

1. Enable downloads at session creation: options.set_capability('se:downloads', True) before instantiating the driver.
2. Confirm the remote server is Selenium 4.x+ and supports the se:downloads capability.
3. Re-create the session with downloads enabled rather than trying to toggle it mid-session.

Example fix

# before
options = webdriver.ChromeOptions()
driver = webdriver.Chrome(options=options)
driver.get_downloadable_files()  # raises

# after
options = webdriver.ChromeOptions()
options.set_capability('se:downloads', True)
driver = webdriver.Chrome(options=options)

if 'se:downloadsEnabled' not in driver.capabilities:
    raise RuntimeError('Enable downloads: options.set_capability("se:downloads", True) at startup')
driver.get_downloadable_files()

def downloads_enabled(driver) -> bool:
    return 'se:downloadsEnabled' in driver.capabilities

from selenium.common.exceptions import WebDriverException
try:
    files = driver.get_downloadable_files()
except WebDriverException:
    files = []  # downloads not enabled for this session

When it happens

Trigger: Calling driver.get_downloadable_files() on a session created without enabling downloads. The check is a simple `if 'se:downloadsEnabled' not in self.capabilities`.

Common situations: Default driver sessions do not enable the downloads capability. A developer tries to fetch a file list after triggering a browser download, forgetting the session was not opted in.

Related errors

• Downloads must be enabled in options
• You must enable downloads in order to work with downloadable
• no capabilities provided for merge
• Capability keys must be strings: ${typeof key}
• Strategy can only be one of the following: normal, eager, no

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