SeleniumHQ/selenium · error · Error

Downloads must be enabled in options

Error message

Downloads must be enabled in options

What it means

Thrown by WebDriver.getDownloadableFiles() and WebDriver.downloadFile() when the session capability 'se:downloadsEnabled' is not present or falsy in the capability map. The code checks caps['map_'].get('se:downloadsEnabled') and throws (as WebDriverError in getDownloadableFiles, as a plain Error in downloadFile) if the capability is missing. This capability must be explicitly opt-in because the Selenium Grid download endpoint exposes server filesystem access.

Source

Thrown at javascript/selenium-webdriver/lib/webdriver.js:1720

      new command.Command(command.Name.SET_USER_VERIFIED)
        .setParameter('authenticatorId', this.authenticatorId_)
        .setParameter('isUserVerified', verified),
    )
  }

  async getDownloadableFiles() {
    const caps = await this.getCapabilities()
    if (!caps['map_'].get('se:downloadsEnabled')) {
      throw new error.WebDriverError('Downloads must be enabled in options')
    }

    return (await this.execute(new command.Command(command.Name.GET_DOWNLOADABLE_FILES))).names
  }

  async downloadFile(fileName, targetDirectory) {
    const caps = await this.getCapabilities()
    if (!caps['map_'].get('se:downloadsEnabled')) {
      throw new Error('Downloads must be enabled in options')
    }

    const response = await this.execute(new command.Command(command.Name.DOWNLOAD_FILE).setParameter('name', fileName))

    const base64Content = response.contents

    if (!targetDirectory.endsWith('/')) {
      targetDirectory += '/'
    }

    fs.mkdirSync(targetDirectory, { recursive: true })
    const zipFilePath = path.join(targetDirectory, `${fileName}.zip`)
    fs.writeFileSync(zipFilePath, Buffer.from(base64Content, 'base64'))

    const zipData = fs.readFileSync(zipFilePath)
    await JSZip.loadAsync(zipData)
      .then((zip) => {
        // Iterate through each file in the zip archive

View on GitHub (pinned to aa36b38e69)

Solutions

  1. Set the se:downloadsEnabled capability to true in your browser options before creating the session: options.setCapability('se:downloadsEnabled', true).
  2. Verify you are connecting to a Selenium Grid (4.x+) that supports the GET_DOWNLOADABLE_FILES and DOWNLOAD_FILE endpoints — local browser drivers do not support remote file retrieval.
  3. Wrap the call in a try/catch to gracefully degrade when downloads are not enabled, rather than crashing the test.

Example fix

// before
const driver = new Builder().forBrowser('chrome').build()
await driver.getDownloadableFiles()  // throws

// after
const options = new chrome.Options()
options.setCapability('se:downloadsEnabled', true)
const driver = new Builder().forBrowser('chrome')
  .setChromeOptions(options).build()
await driver.getDownloadableFiles()
Defensive patterns

Strategy: validation

Validate before calling

const caps = await driver.getCapabilities()
if (caps.get('se:downloadsEnabled')) {
  const files = await driver.getDownloadableFiles()
}

Try / catch

try {
  const files = await driver.getDownloadableFiles()
} catch (e) {
  if (/Downloads must be enabled/.test(e.message)) {
    // inform user to set se:downloadsEnabled
  } else throw e
}

Prevention

When it happens

Trigger: Calling driver.getDownloadableFiles() or driver.downloadFile(fileName, targetDirectory) on a session whose browser options did not include se:downloadsEnabled = true. The capability is checked before the corresponding WebDriver command is even sent to the server.

Common situations: Running against a Selenium Grid and forgetting to enable downloads in the browser Options; using a local driver where the download endpoint is unavailable; upgrading Selenium Grid and not re-setting the capability in the new options object; the Grid version does not support the download endpoints.

Related errors

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