What causes "image.resolve: 'name' is required" in karatelabs/karate?

Pass the baseline name as a string: karate.call('image.resolve', 'screenshot-home')

karatelabs/karate · error · RuntimeException

image.resolve: 'name' is required

Error message

image.resolve: 'name' is required

What it means

The image.resolve verb maps a baseline name to absolute baseline and options paths. It requires the first argument to be a non-empty name; with no args or a null/unresolvable first arg it throws RuntimeException with this message.

Solutions

Pass the baseline name as a string: karate.call('image.resolve', 'screenshot-home')
Ensure the variable holding the name is set and is a String before calling
If you have a path instead of a name, use the path directly rather than the resolve verb

Example fix

// before
var name = karate.get('baselineName'); // null
karate.call('image.resolve', name);
// after
karate.set('baselineName', 'screenshot-home');
karate.call('image.resolve', karate.get('baselineName'));

Defensive patterns

Strategy: validation

Validate before calling

# karate
* if (!baselineName) karate.abort('baselineName must be set before image.resolve')
* def resolved = karate.call('image.resolve', baselineName)

Try / catch

try { return karate.call('image.resolve', name); } catch (Exception e) { if (('' + e).contains("'name' is required")) throw new IllegalStateException("image.resolve called without a name — baselineName=" + name); throw e; }

Prevention

Initialize the baseline-name variable at the top of the feature
Pass names as plain strings, never as maps or nulls
Keep baseline naming in one shared helper

When it happens

Trigger: karate.call('image.resolve') with zero arguments, or with a first argument that str() maps to null (null, or an object/array rather than a string).

Common situations: Scripting resolution dynamically and the variable holding the name is null; calling resolve programmatically without args to 'probe' behavior; passing the bytes of an image instead of its name by mistake.

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

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

Appendix: source

Thrown at karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java:319

        Map<String, Object> embed = new LinkedHashMap<>();
        embed.put("name", "image-comparison");
        embed.put("parts", parts);
        embed.put("meta", meta);
        return embed;
    }

    private static Map<String, Object> part(String role, byte[] data) {
        Map<String, Object> p = new LinkedHashMap<>();
        p.put("role", role);
        p.put("data", data);   // mime auto-detected by karate.embed from the bytes
        return p;
    }

    // ---- resolve (name → absolute baseline + options paths) ----

    private Object resolveVerb(Object... args) {
        if (args.length == 0 || str(args[0]) == null) {
            throw new RuntimeException("image.resolve: 'name' is required");
        }
        return resolve(str(args[0]));
    }

    private Map<String, Object> resolve(String name) {
        String base = stripExt(name);
        boolean hasExt = !base.equals(name);
        String baselineLeaf = hasExt ? name : findBaselineLeaf(base);
        String baselineJoined = join(str(config.get("baselineDir")), baselineLeaf);

        Map<String, Object> out = new LinkedHashMap<>();
        out.put("baselinePath", absolute(baselineJoined));
        out.put("optionsPath", absolute(join(optionsDir(), base + ".json")));
        out.put("baselineExists", resourceExists(baselineJoined));
        return out;
    }

    /**

View on GitHub (pinned to a22eb90246)