karatelabs/karate · error · DriverException

locator cannot be null or empty

Error message

locator cannot be null or empty

What it means

Locators.selector validates the locator argument before converting it into a JS expression; null or empty-string locators cannot be meaningfully converted, so a DriverException is thrown immediately. Called by all single-element lookup paths including the js() variants.

Solutions

1. Ensure the locator string is populated before the call — check upstream variable/config values
2. Add an early guard that fails the test with a clear message when the locator is blank
3. Fix test data so environment-specific locator variables have values

Example fix

// before
String loc = karate.get("searchBox"); // null in this env
driver.locate(loc);
// after
String loc = karate.get("searchBox", "input[name='q']");
if (loc == null || loc.isEmpty()) throw new RuntimeException("searchBox locator missing");
driver.locate(loc);

if (locator == null || locator.isEmpty()) {
    throw new IllegalArgumentException("locator must be provided");
}
driver.locate(locator);

boolean isValidLocator(String s) { return s != null && !s.isEmpty(); }

try {
    driver.locate(loc);
} catch (DriverException e) {
    if (e.getMessage().equals("locator cannot be null or empty")) {
        throw new IllegalStateException("locator config missing for: " + key, e);
    } throw e;
}

When it happens

Trigger: Passing null or "" to karate locator APIs such as driver.locate(""), Element methods, or Locators.selector/selector-based JS builders where the locator string was never populated.

Common situations: Locators built dynamically from config/variables that are empty in a given environment, refactored test data where the variable lost its value, copying examples that left the locator blank.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• bad wildcard locator
• locator is not a frame
• element not found after
• karate.driver can only be read within a scenario
• embed(): each 'parts' entry must be an object

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/178294faeceb536f. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/Locators.java:88

     * Transform a locator into a JavaScript expression that returns a single element.
     *
     * @param locator CSS selector, XPath, wildcard, or JS expression
     * @return JavaScript expression
     */
    public static String selector(String locator) {
        return selector(locator, DOCUMENT);
    }

    /**
     * Transform a locator into a JavaScript expression with a context node.
     *
     * @param locator     CSS selector, XPath, wildcard, or JS expression
     * @param contextNode JavaScript expression for the context node
     * @return JavaScript expression
     */
    public static String selector(String locator, String contextNode) {
        if (locator == null || locator.isEmpty()) {
            throw new DriverException("locator cannot be null or empty");
        }

        // Pure JS expression - pass through (but not XPath starting with parenthesis)
        if (locator.startsWith("(") && !locator.startsWith("(//")) {
            return locator;
        }

        // Wildcard: {div}text or {^div}partial or {tag:2}text
        // Returns JS expression directly (no further processing needed)
        if (locator.startsWith("{")) {
            return expandWildcard(locator);
        }

        // XPath
        if (isXpath(locator)) {
            return xpathSelector(locator, contextNode);
        }

View on GitHub (pinned to a22eb90246)