karatelabs/karate · error · RuntimeException

image.diff: need a name or a baseline (and a latest)

Error message

image.diff: need a name or a baseline (and a latest)

What it means

ImageApi.diff compares a baseline image to a latest image. It requires either a named baseline (resolved to baselinePath + optionsPath from prior image.write calls) or explicit baseline and latest inputs; if neither is provided it throws RuntimeException with this message.

Solutions

1. Pass a name that was previously established: { name: 'screenshot-home' }
2. Or pass explicit images: { baseline: <bytes>, latest: <bytes> }
3. Call image.write with the baseline first so the name resolves to a baselinePath
4. Verify the argument keys are exactly 'name', 'baseline', 'latest'

Example fix

// before
karate.call('image.diff', { fuzzy: 0.1 }); // no name/baseline
// after
karate.call('image.diff', { name: 'screenshot-home', fuzzy: 0.1 });

# karate
* if (!args.name && !(args.baseline && args.latest)) karate.abort('image.diff needs name or baseline+latest')

try { karate.call('image.diff', { name: name }); } catch (Exception e) { if (('' + e).contains('need a name or a baseline')) { karate.call('image.write', name, latest); return karate.call('image.diff', { name: name }); } throw e; }

When it happens

Trigger: Calling karate.call('image.diff') (or the diff verb) with arguments that include neither a 'name' key nor 'baseline'+'latest' byte arrays — e.g. an empty arg map, or only options without images.

Common situations: Running image comparison before any baseline was written via image.write, so the name lookup has no recipe; forgetting the 'name' field in the diff call args; a typo'd key ('imageName' instead of 'name').

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

• image.resolve: 'name' is required
• image.write: needs (name|path, bytes)
• readAsStream() needs at least one argument
• image: failed to read options
• image.write: failed to write

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

Appendix: source

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

        Object baselineArg = call.get("baseline");
        String baselinePath = null;
        String optionsPath = null;
        byte[] baseline;

        Map<String, Object> options = new LinkedHashMap<>();
        if (baselineArg instanceof String s) {
            baselinePath = absolute(s);          // explicit path: no <name>.json auto-load
            baseline = readBytes(s);
        } else if (baselineArg != null) {
            baseline = toBytes(baselineArg);     // explicit baseline bytes / Uint8Array
        } else if (name != null) {
            Map<String, Object> resolved = resolve(name);
            baselinePath = str(resolved.get("baselinePath"));
            optionsPath = str(resolved.get("optionsPath"));
            options.putAll(loadOptionsFile(optionsPath));   // file opts: low precedence
            baseline = readBytes(baselinePath);
        } else {
            throw new RuntimeException("image.diff: need a name or a baseline (and a latest)");
        }

        // per-call inline options (everything that isn't structural) override the file
        for (Map.Entry<String, Object> e : call.entrySet()) {
            if (!STRUCTURAL.contains(e.getKey())) {
                options.put(e.getKey(), e.getValue());
            }
        }
        if (options.containsKey("threshold")) {
            options.put("failureThreshold", options.remove("threshold"));
        }
        String reportName = name != null ? name : str(options.get("name"));
        if (reportName != null) {
            options.put("name", reportName);
        }

        Map<String, Object> r = ImageComparison.run(baseline, latest, options, defaultOptions());
        return result(r, reportName, options, baseline, latest, baselinePath, optionsPath);

View on GitHub (pinned to a22eb90246)