{"record":{"id":"178294faeceb536f","repo":"karatelabs/karate","slug":"locator-cannot-be-null-or-empty","errorCode":null,"errorMessage":"locator cannot be null or empty","messagePattern":"locator cannot be null or empty","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/Locators.java","lineNumber":88,"sourceCode":"     * Transform a locator into a JavaScript expression that returns a single element.\n     *\n     * @param locator CSS selector, XPath, wildcard, or JS expression\n     * @return JavaScript expression\n     */\n    public static String selector(String locator) {\n        return selector(locator, DOCUMENT);\n    }\n\n    /**\n     * Transform a locator into a JavaScript expression with a context node.\n     *\n     * @param locator     CSS selector, XPath, wildcard, or JS expression\n     * @param contextNode JavaScript expression for the context node\n     * @return JavaScript expression\n     */\n    public static String selector(String locator, String contextNode) {\n        if (locator == null || locator.isEmpty()) {\n            throw new DriverException(\"locator cannot be null or empty\");\n        }\n\n        // Pure JS expression - pass through (but not XPath starting with parenthesis)\n        if (locator.startsWith(\"(\") && !locator.startsWith(\"(//\")) {\n            return locator;\n        }\n\n        // Wildcard: {div}text or {^div}partial or {tag:2}text\n        // Returns JS expression directly (no further processing needed)\n        if (locator.startsWith(\"{\")) {\n            return expandWildcard(locator);\n        }\n\n        // XPath\n        if (isXpath(locator)) {\n            return xpathSelector(locator, contextNode);\n        }\n","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/Locators.java#L70-L106","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the locator string is populated before the call — check upstream variable/config values","Add an early guard that fails the test with a clear message when the locator is blank","Fix test data so environment-specific locator variables have values"],"exampleFix":"// before\nString loc = karate.get(\"searchBox\"); // null in this env\ndriver.locate(loc);\n// after\nString loc = karate.get(\"searchBox\", \"input[name='q']\");\nif (loc == null || loc.isEmpty()) throw new RuntimeException(\"searchBox locator missing\");\ndriver.locate(loc);","handlingStrategy":"validation","validationCode":"if (locator == null || locator.isEmpty()) {\n    throw new IllegalArgumentException(\"locator must be provided\");\n}\ndriver.locate(locator);","typeGuard":"boolean isValidLocator(String s) { return s != null && !s.isEmpty(); }","tryCatchPattern":"try {\n    driver.locate(loc);\n} catch (DriverException e) {\n    if (e.getMessage().equals(\"locator cannot be null or empty\")) {\n        throw new IllegalStateException(\"locator config missing for: \" + key, e);\n    } throw e;\n}","preventionTips":["Default locator variables at read time (karate.get(key, default))","Fail fast on blank config values during setup","Keep locators in one validated config file"],"tags":["driver","locator","validation"],"backgroundTag":"empty-required-field","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}