{"record":{"id":"bf739c7cba3adbad","repo":"SeleniumHQ/selenium","slug":"downloads-must-be-enabled-in-options","errorCode":null,"errorMessage":"Downloads must be enabled in options","messagePattern":"Downloads must be enabled in options","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"javascript/selenium-webdriver/lib/webdriver.js","lineNumber":1720,"sourceCode":"      new command.Command(command.Name.SET_USER_VERIFIED)\n        .setParameter('authenticatorId', this.authenticatorId_)\n        .setParameter('isUserVerified', verified),\n    )\n  }\n\n  async getDownloadableFiles() {\n    const caps = await this.getCapabilities()\n    if (!caps['map_'].get('se:downloadsEnabled')) {\n      throw new error.WebDriverError('Downloads must be enabled in options')\n    }\n\n    return (await this.execute(new command.Command(command.Name.GET_DOWNLOADABLE_FILES))).names\n  }\n\n  async downloadFile(fileName, targetDirectory) {\n    const caps = await this.getCapabilities()\n    if (!caps['map_'].get('se:downloadsEnabled')) {\n      throw new Error('Downloads must be enabled in options')\n    }\n\n    const response = await this.execute(new command.Command(command.Name.DOWNLOAD_FILE).setParameter('name', fileName))\n\n    const base64Content = response.contents\n\n    if (!targetDirectory.endsWith('/')) {\n      targetDirectory += '/'\n    }\n\n    fs.mkdirSync(targetDirectory, { recursive: true })\n    const zipFilePath = path.join(targetDirectory, `${fileName}.zip`)\n    fs.writeFileSync(zipFilePath, Buffer.from(base64Content, 'base64'))\n\n    const zipData = fs.readFileSync(zipFilePath)\n    await JSZip.loadAsync(zipData)\n      .then((zip) => {\n        // Iterate through each file in the zip archive","sourceCodeStart":1702,"sourceCodeEnd":1738,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/javascript/selenium-webdriver/lib/webdriver.js#L1702-L1738","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the se:downloadsEnabled capability to true in your browser options before creating the session: options.setCapability('se:downloadsEnabled', true).","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.","Wrap the call in a try/catch to gracefully degrade when downloads are not enabled, rather than crashing the test."],"exampleFix":"// before\nconst driver = new Builder().forBrowser('chrome').build()\nawait driver.getDownloadableFiles()  // throws\n\n// after\nconst options = new chrome.Options()\noptions.setCapability('se:downloadsEnabled', true)\nconst driver = new Builder().forBrowser('chrome')\n  .setChromeOptions(options).build()\nawait driver.getDownloadableFiles()","handlingStrategy":"validation","validationCode":"const caps = await driver.getCapabilities()\nif (caps.get('se:downloadsEnabled')) {\n  const files = await driver.getDownloadableFiles()\n}","typeGuard":null,"tryCatchPattern":"try {\n  const files = await driver.getDownloadableFiles()\n} catch (e) {\n  if (/Downloads must be enabled/.test(e.message)) {\n    // inform user to set se:downloadsEnabled\n  } else throw e\n}","preventionTips":["Set se:downloadsEnabled: true in browser options when using Selenium Grid download features.","Only call getDownloadableFiles/downloadFile against a Selenium Grid 4.x endpoint.","Wrap download calls in try/catch for graceful degradation."],"tags":["javascript","downloads","selenium-grid","capabilities","webdriver"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}