What causes "Cannot locate an element with provided parameters" in SeleniumHQ/selenium?

Replace findElement() with findElements() and check the returned array length before indexing, so an empty result does not throw.

SeleniumHQ/selenium · error · NoSuchElementError

Cannot locate an element with provided parameters

Error message

Cannot locate an element with provided parameters

What it means

Thrown as a NoSuchElementError by WebDriver.normalize_() when a locator function resolves to an empty array. This method is invoked by the singular findElement() flow: it resolves the locator promise, expects a list of WebElements, and throws if that list has zero entries. It represents the W3C WebDriver 'no such element' condition when the JavaScript locator itself returns nothing before any remote round-trip.

Source

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

        .setParameter('value', locator.value)
    }

    id = this.execute(cmd)
    if (locator instanceof RelativeBy) {
      return this.normalize_(id)
    } else {
      return new WebElementPromise(this, id)
    }
  }

  /**
   * @param {!Function} webElementPromise The webElement in unresolved state
   * @return {!Promise<!WebElement>} First single WebElement from array of resolved promises
   */
  async normalize_(webElementPromise) {
    let result = await webElementPromise
    if (result.length === 0) {
      throw new NoSuchElementError('Cannot locate an element with provided parameters')
    } else {
      return result[0]
    }
  }

  /**
   * @param {!Function} locatorFn The locator function to use.
   * @param {!(WebDriver|WebElement)} context The search context.
   * @return {!Promise<!WebElement>} A promise that will resolve to a list of
   *     WebElements.
   * @private
   */
  async findElementInternal_(locatorFn, context) {
    let result = await locatorFn(context)
    if (Array.isArray(result)) {
      if (result.length === 0) {
        throw new NoSuchElementError('Cannot locate an element with provided parameters')
      }

View on GitHub (pinned to aa36b38e69)

Solutions

Replace findElement() with findElements() and check the returned array length before indexing, so an empty result does not throw.
Add an explicit wait using webdriver.until.elementLocated(locator) before calling findElement(), giving the page time to render the element.
Verify the locator strategy and selector against the current DOM using browser devtools — a stale class name or changed structure is the most frequent cause.
If the element is legitimately optional, wrap the call in a try/catch for NoSuchElementError and handle the absence gracefully.

Example fix

// before
element = await driver.findElement(By.css('.maybe-missing'))

// after
const elements = await driver.findElements(By.css('.maybe-missing'))
if (elements.length === 0) {
  console.log('Element not present; skipping')
} else {
  element = elements[0]
}
// or with a wait:
element = await driver.wait(
  webdriver.until.elementLocated(By.css('.maybe-missing')), 5000
)

Defensive patterns

Strategy: validation

Validate before calling

// Use findElements instead of findElement to avoid the throw
const elements = await driver.findElements(locator)
if (elements.length > 0) {
  const element = elements[0] // safe
}

Type guard

// Check array before treating as single element
function hasElement(arr) {
  return Array.isArray(arr) && arr.length > 0
}

Try / catch

try {
  const el = await driver.findElement(locator)
} catch (e) {
  if (e instanceof webdriver.error.NoSuchElementError) {
    // element legitimately absent
  } else throw e
}

Prevention

Prefer findElements() + length check over findElement() when absence is possible.
Always use explicit waits (driver.wait) before findElement() for dynamically loaded content.
Verify selectors against current DOM before running tests.

When it happens

Trigger: Calling driver.findElement(locator) or element.findElement(locator) where the underlying locator function (e.g. By.js, a custom locator, or js-based locator) returns an array with length 0. Specifically, normalize_() is called on the unresolved webElementPromise; if `await webElementPromise` yields an empty array, the error fires.

Common situations: Page has not loaded the target element yet (no explicit wait), element selector changed after a UI refactor, the locator targets a dynamically-rendered component that is conditionally absent, or a custom locator function returns [] for a page state the test did not anticipate.

Related errors

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