SeleniumHQ/selenium · error · TypeError

Invalid locator

Error message

Invalid locator

What it means

Thrown by checkedLocator() (exported as checkedLocator) in by.js when the input cannot be resolved into a valid By or RelativeBy. The function checks for By/RelativeBy instances, functions, hash objects with using/value string fields, and objects whose keys match By static methods. If none match, this TypeError fires.

Source

Thrown at javascript/selenium-webdriver/lib/by.js:469

  if (locator instanceof By || locator instanceof RelativeBy || typeof locator === 'function') {
    return locator
  }

  if (
    locator &&
    typeof locator === 'object' &&
    typeof locator.using === 'string' &&
    typeof locator.value === 'string'
  ) {
    return new By(locator.using, locator.value)
  }

  for (let key in locator) {
    if (Object.prototype.hasOwnProperty.call(locator, key) && Object.prototype.hasOwnProperty.call(By, key)) {
      return By[key](locator[key])
    }
  }
  throw new TypeError('Invalid locator')
}

// PUBLIC API

module.exports = {
  By,
  RelativeBy,
  withTagName,
  locateWith,
  escapeCss,
  checkedLocator: check,
}

View on GitHub (pinned to aa36b38e69)

Solutions

1. Use explicit By factories: By.css('#id'), By.xpath('//div'), By.id('id').
2. Verify locator hash keys match By method names exactly (css, xpath, id, className, name, tagName, linkText, partialLinkText).
3. Check for null/undefined before passing to findElement/findElements.
4. Use the By constant directly rather than a hash object.

Example fix

// before
driver.findElement({ csss: '#foo' })
// after
driver.findElement({ css: '#foo' })
// or even better
driver.findElement(By.css('#foo'))

const { By } = require('selenium-webdriver')
const VALID_BY_KEYS = new Set(['css', 'className', 'id', 'name', 'tagName', 'linkText', 'partialLinkText', 'xpath', 'js'])
function isValidLocatorHash(obj) {
  return Object.keys(obj).some((k) => VALID_BY_KEYS.has(k))
}
if (locator == null || (typeof locator === 'object' && !isValidLocatorHash(locator))) {
  throw new TypeError('Invalid locator: use By.css(), By.xpath(), etc.')
}

/**
 * @param {*} l
 * @returns {boolean}
 */
function isValidLocator(l) {
  if (l instanceof By || l instanceof RelativeBy || typeof l === 'function') return true
  if (l && typeof l === 'object') {
    if (typeof l.using === 'string' && typeof l.value === 'string') return true
    return Object.keys(l).some((k) => typeof By[k] === 'function')
  }
  return false
}

When it happens

Trigger: Passing null, undefined, an empty object, or a plain object whose keys don't match any By method (e.g., {csss:'#foo'}). Passing a number or string directly instead of a locator object.

Common situations: Dynamically constructing locators from config or untrusted data; typos in By hash keys; passing a raw selector string where an object is expected; passing an object with custom keys.

Related errors

• input must be a string
• Did not know how to convert ${value} into color
• Cannot locate option with value: ${value}
• Cannot locate option with text: ${text}
• Compound class names are not allowed.

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