karatelabs/karate · error · RuntimeException

xmlPath() first argument must be XML node or string, but was

Error message

xmlPath() first argument must be XML node or string, but was: {class}

What it means

karate.xmlPath() accepts its XML source as a DOM Node or a String (which is parsed via Xml.toXmlDoc). Any other type — including null — cannot be evaluated, so the library throws this error, appending the value's class name (or 'null'). This is the source-type guard immediately before XPath evaluation.

Solutions

1. Pass the raw XML string or a DOM Node as the first argument: karate.xmlPath(xmlString, path).
2. If your data is JSON, use JSON path (karate's json handling) instead of xmlPath.
3. Guard against null: ensure the variable holding the XML is populated before the call.
4. The message tells you the offending class — use it to identify which wrong value leaked in.

Example fix

// before
karate.xmlPath(response, '/order/id') // response is JSON
// after
karate.xmlPath(responseXml, '/order/id')

if (xml == null) { throw new Error('xmlPath() source is null — check the earlier request/variable') }
if (typeof xml !== 'string' && ('' + xml).charAt(0) !== '<') { karate.logger.warn('xmlPath() source does not look like XML') }

function isXmlSource(v) { return v != null && (typeof v === 'string' || v.getClass && String(v.getClass()).indexOf('Node') >= 0 || (typeof v === 'object' && String(v).indexOf('#document') >= 0)) }

try { var val = karate.xmlPath(xml, path) } catch (e) { if (('' + e).indexOf('first argument must be XML node or string') >= 0) { karate.logger.warn('xmlPath source wrong type: ' + ('' + e)); val = null } throw e }

When it happens

Trigger: karate.xmlPath(someJsonObject, '/path') passing a Map/JSON instead of XML; passing null because an earlier request returned nothing; passing a number or byte array.

Common situations: Confusing a JSON response with an XML response in a test; XML variable not yet defined (null) at call time; passing an already-extracted value instead of the raw XML document.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• xmlPath() needs two arguments: xml and path
• toBytes() argument must be a list of numbers, got
• toBytes() list must contain only numbers, got
• read() needs at least one argument
• sysenv() needs the environment-variable name

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

Appendix: source

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

    /**
     * karate.xmlPath(xml, path) - Evaluate XPath on XML.
     * First argument can be XML Node or String.
     */
    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);

View on GitHub (pinned to a22eb90246)