karatelabs/karate · error · DriverException

bad wildcard locator

Error message

bad wildcard locator: {locator}

What it means

expandWildcard converts Karate wildcard locators like {div}, {:2}text, {^}text into JS resolver expressions. When the locator starts like a wildcard but does not match the wildcard grammar (WILDCARD_PATTERN), it cannot be expanded and a DriverException is thrown.

Solutions

  1. Fix the wildcard syntax to match the supported grammar (e.g. {div}, {div}text, {:2}text, {^}text)
  2. If it is not meant to be a wildcard, remove the leading '{' or use an explicit 'css:'/'xpath:' prefix
  3. Log/print the composed locator string to spot malformed interpolation

Example fix

// before
driver.locate("{div'); // malformed
// after
driver.locate("{div}Submit"); // wildcard: div containing text 'Submit'
Defensive patterns

Strategy: validation

Validate before calling

// only pass '{'-prefixed strings that match known wildcard forms
if (locator.startsWith("{") && !locator.matches("\{\^?\w*(::?\d+)?\}.*|\{\^?\w*\}.*")) {
    throw new IllegalArgumentException("malformed wildcard locator: " + locator);
}

Try / catch

try {
    driver.locate(wildcard);
} catch (DriverException e) {
    if (e.getMessage().startsWith("bad wildcard locator")) {
        throw new IllegalArgumentException("Use forms like {div}, {div}text, {:2}text, {^}text: " + wildcard, e);
    } throw e;
}

Prevention

When it happens

Trigger: Passing a malformed wildcard such as '{div' (unclosed), '{:}' (empty parts), or '{foo:bar:baz}' — any '{'-prefixed string that fails the pattern for tag/index/text groups.

Common situations: Typos in wildcard syntax, mixing wildcard syntax with css/xpath prefixes, upgrading Karate versions where wildcard grammar was tightened, hand-written wildcards generated from variables.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

        return false;
    }

    // ========== Wildcard Locator Expansion ==========

    /**
     * Expand wildcard locator to JavaScript resolver call.
     * Uses browser-side JS that matches the same logic as locator generation.
     * <ul>
     *   <li>{tag}text     → window.__kjs.resolve('tag', 'text', 1, false)</li>
     *   <li>{^tag}text    → window.__kjs.resolve('tag', 'text', 1, true)</li>
     *   <li>{tag:2}text   → window.__kjs.resolve('tag', 'text', 2, false)</li>
     *   <li>{:2}text      → window.__kjs.resolve('*', 'text', 2, false)</li>
     * </ul>
     */
    public static String expandWildcard(String locator) {
        Matcher m = WILDCARD_PATTERN.matcher(locator);
        if (!m.matches()) {
            throw new DriverException("bad wildcard locator: " + locator);
        }

        boolean contains = m.group(1) != null;  // ^ prefix
        String tagPart = m.group(2);
        String indexPart = m.group(3);
        String text = m.group(4);

        String tag = (tagPart == null || tagPart.isEmpty()) ? "*" : tagPart;
        int index = (indexPart != null) ? Integer.parseInt(indexPart) : 1;

        // Build JS resolver call
        String escapedTag = escapeForJs(tag);
        String escapedText = escapeForJs(text);
        return "window.__kjs.resolve(\"" + escapedTag + "\", \"" + escapedText + "\", " + index + ", " + contains + ")";
    }

    // ========== XPath Selector ==========

View on GitHub (pinned to a22eb90246)