karatelabs/karate · error · JsErrorException

iterator. is not a function

Error message

iterator.${name} is not a function

What it means

Karate resolves an iterator method (next/return/throw) by name from the iterator object. When required (e.g. next()) and the property is missing or undefined, it throws 'iterator.<name> is not a function'. This enforces the iterator protocol's minimum shape before invoking the method.

Solutions

1. Ensure the object passed where an iterator is expected has a callable next() method
2. Pass the iterable itself (with Symbol.iterator) rather than a hand-shaped object, letting the engine obtain a correct iterator
3. If iterating Java collections or arrays, use the engine's supported forms (for-of over the collection) instead of a custom wrapper

Example fix

// before
for (const x of { next: myNext }) {...} // next not callable/undefined
// after
for (const x of makeIterable()) {...} // object with [Symbol.iterator](){ return { next: () => ({done,value}) } }

if (!it || typeof it.next !== 'function') throw new TypeError('expected an iterator with next()');

function isIterator(x) { return x != null && typeof x.next === 'function'; }

try { for (const v of it) {...} } catch (e) { if (String(e).includes('iterator.next is not a function')) { /* obtain proper iterator via Symbol.iterator */ } }

When it happens

Trigger: Passing an object without a next() method where an iterator is expected (for-of, spread, IterUtils.getIterator adapters for strings/lists/Java iterables), or an iterator whose next was deleted or renamed.

Common situations: Typing mistakes like nex() or Next(); destructuring an iterator and passing the extracted next as a bound-less property; passing plain objects or Java collections through paths that expect protocol-shaped iterators.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Result of the Symbol.iterator method is not an object
• iterator result is not an object
• The iterator does not provide a 'throw' method
• iterator.throw is not a function
• Iterator value is not an entry object

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/js/Interpreter.java:3049

            sent = sig.value;
        }
    }

    /** Invoke {@code iterObj[name](arg)} with {@code iterObj} as `this`.
     *  Spec GetMethod semantics: a nullish member is absent (TypeError when
     *  {@code required}, null return otherwise — caller decides); a PRESENT
     *  non-callable member is always a TypeError. A null {@code arg} means
     *  call with no arguments. Cooperative errors surface via
     *  context.isStopped(). */
    private static Object invokeIteratorMethod(ObjectLike iterObj, String name, Object arg,
                                               CoreContext context, boolean required) {
        Object fn = iterObj.getMember(name, iterObj, context);
        if (context.isStopped()) {
            return Terms.UNDEFINED;
        }
        if (fn == null || fn == Terms.UNDEFINED) {
            if (required) {
                throw JsErrorException.typeError("iterator." + name + " is not a function");
            }
            return null;
        }
        if (!(fn instanceof JsCallable callable)) {
            throw JsErrorException.typeError("iterator." + name + " is not a function");
        }
        Object result = invokeIteratorCallable(iterObj, callable, arg, context);
        if (!context.isStopped() && required && !(result instanceof ObjectLike)) {
            throw JsErrorException.typeError("iterator result is not an object");
        }
        return result;
    }

    private static Object invokeIteratorCallable(ObjectLike iterObj, JsCallable callable,
                                                 Object arg, CoreContext context) {
        Object savedThis = context.thisObject;
        context.thisObject = iterObj;
        try {

View on GitHub (pinned to a22eb90246)