SeleniumHQ/selenium · error · Error::WebDriverError

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

The HasFileDownloads extension methods (downloadable_files, download_file, delete_downloadable_files) call verify_enabled, which requires the session capability 'se:downloadsEnabled' to be truthy. If you did not opt into downloads when creating the session, the capability is absent and these methods raise Error::WebDriverError.

Source

Thrown at rb/lib/selenium/webdriver/common/driver_extensions/has_file_downloads.rb:66

              end
            end
          ensure
            FileUtils.rm_f("#{file_name}.zip")
          end
        end

        def delete_downloadable_files
          verify_enabled

          @bridge.delete_downloadable_files
        end

        private

        def verify_enabled
          return if capabilities['se:downloadsEnabled']

          raise Error::WebDriverError, 'You must enable downloads in order to work with downloadable files.'
        end
      end # HasFileDownloads
    end # DriverExtensions
  end # WebDriver
end # Selenium

View on GitHub (pinned to aa36b38e69)

Solutions

1. Enable downloads in capabilities at session creation: caps['se:downloadsEnabled'] = true (or via the appropriate Options).
2. Use a Remote driver against a Selenium Grid that supports downloads; this is not a local-browser feature.
3. Upgrade Selenium Grid/server to a version that honors 'se:downloadsEnabled'.
4. Call verify_enabled-equivalent logic yourself and degrade gracefully if the capability is missing.

Example fix

// before
caps = Selenium::WebDriver::Remote::Capabilities.chrome
driver = Selenium::WebDriver.for(:remote, capabilities: caps)
driver.downloadable_files
// after
caps = Selenium::WebDriver::Remote::Capabilities.chrome
caps['se:downloadsEnabled'] = true
driver = Selenium::WebDriver.for(:remote, capabilities: caps)
driver.downloadable_files

def downloads_enabled?(driver)
  driver.capabilities['se:downloadsEnabled']
end

raise 'downloads not enabled' unless downloads_enabled?(driver)
driver.downloadable_files

def downloads_enabled?(capabilities)
  !!capabilities['se:downloadsEnabled']
end

begin
  driver.downloadable_files
rescue Selenium::WebDriver::Error::WebDriverError => e
  raise unless e.message =~ /must enable downloads/
  warn 'recreate session with se:downloadsEnabled = true'
end

When it happens

Trigger: Calling driver.downloadable_files / driver.download_file(...) / driver.delete_downloadable_files on a session created without the downloads capability enabled.

Common situations: Forgetting to set 'se:downloadsEnabled' => true in capabilities, using a local driver instead of Remote (this is a Grid/Remote feature), capability name typo, older Selenium Grid that does not support it.

Related errors

• Downloads must be enabled in options
• You must enable downloads in order to work with downloadable
• These options are not w3c compliant: #{options}
• BiDi was enabled, but the remote end did not return a valid
• Safari does not support options that are not namespaced

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