karatelabs/karate · error · RuntimeException

xmlPath failed for path

Error message

xmlPath failed for path: {path} - {message}

What it means

karate.xmlPath() wraps any failure from the internal XPath evaluator (evalXmlPath) in a RuntimeException that includes the offending path and the underlying message. It is thrown whenever the XPath expression cannot be evaluated against the given XML document — bad syntax, no matching function, or a type-incompatible result.

Solutions

1. Validate the XPath expression syntax; test it in an XPath playground against the actual XML
2. Remove JsonPath ($, $.) prefixes — xmlPath expects plain XPath, e.g. '/root/child'
3. Simplify the expression: use basic axis/node tests and supported functions only
4. Check the nested 'caused by' in the error for the precise XPath failure

Example fix

// before
String v = karate.xmlPath(xml, '$.root.child');
// after
String v = karate.xmlPath(xml, '/root/child');

// JS: sanity-check the XPath before calling
if (typeof path !== 'string' || !path.startsWith('/')) throw new Error('XPath must start with /: ' + path);

// Java
static boolean isXPath(String p) { return p != null && p.trim().startsWith("/") && !p.startsWith("$."); }

try {
    String v = karate.xmlPath(xml, '/root/child');
} catch (Exception e) {
    karate.logger.warn('xmlPath failed: {}', e.getMessage());
    v = null;
}

When it happens

Trigger: Calling karate.xmlPath(nodeOrString, path) where path is a malformed XPath expression, uses an unsupported function, or the first argument is valid XML but the expression cannot be evaluated (the preceding guard already rejects non-XML first args with a different message).

Common situations: Typos in XPath like '/foo/bar[@id]' missing a value; using Karate's JsonPath-style '$.' prefixes on XML; relying on XPath 2.0+ functions not supported by the underlying engine.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• cannot set xpath on non-XML variable:
• xmlPath() needs two arguments: xml and path
• xmlPath() first argument must be XML node or string, but was
• no results for xpath
• remove() needs two arguments: variable name and path

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java:979

    static JavaInvokable xmlPath() {
        return args -> {
            if (args.length < 2) {
                throw new RuntimeException("xmlPath() needs two arguments: xml and path");
            }
            Object xmlObj = args[0];
            String path = args[1].toString();
            Node doc;
            if (xmlObj instanceof Node) {
                doc = (Node) xmlObj;
            } else if (xmlObj instanceof String) {
                doc = Xml.toXmlDoc((String) xmlObj);
            } else {
                throw new RuntimeException("xmlPath() first argument must be XML node or string, but was: " + (xmlObj == null ? "null" : xmlObj.getClass()));
            }
            try {
                return evalXmlPath(doc, path);
            } catch (Exception e) {
                throw new RuntimeException("xmlPath failed for path: " + path + " - " + e.getMessage(), e);
            }
        };
    }

    // ========== Control Flow Utilities ==========

    /**
     * karate.fail(message) - Explicitly fail the scenario with a message.
     */
    static JavaInvokable fail() {
        return args -> {
            String message = args.length > 0 && args[0] != null ? args[0].toString() : "karate.fail() called";
            throw new RuntimeException(message);
        };
    }

    // ========== Type Conversion Utilities (Invokable) ==========

View on GitHub (pinned to a22eb90246)