karatelabs/karate · error · RuntimeException

image.diff: 'latest' image (bytes or path) is required

Error message

image.diff: 'latest' image (bytes or path) is required

What it means

Karate's image.diff() requires a 'latest' screenshot/image to compare against the baseline. requireLatest() extracts the 'latest' key from the map-style call and throws when it is absent, null, or cannot be converted to bytes (empty byte[]-like value). The library cannot perform a visual diff without an actual image to compare.

Solutions

1. Add a non-null 'latest' value: image.diff({ baseline: 'base.png', latest: 'latest.png' })
2. Pass the latest image as a path string, byte[], or Uint8Array to image.diff(name, latest)
3. Log/verify the latest variable in JS before calling diff (it must be defined)
4. Check for key typos: the key must be exactly 'latest'

Example fix

// before
image.diff({ baseline: 'base.png' }) // missing latest
// after
image.diff({ baseline: 'base.png', latest: 'latest.png' })

// JS before calling diff
karate.log('latest value:', latest);
if (latest == null) karate.fail("'latest' image is required before image.diff");
image.diff({ baseline: 'base.png', latest: latest });

When it happens

Trigger: Calling image.diff({...}) (or the latest() overload that routes through requireLatest) with: no 'latest' key at all, latest: null, or a 'latest' value that resolves to null bytes (e.g. undefined JS variable).

Common situations: A typo in the map key ('lastest', 'Latest'); the variable holding the screenshot was never assigned or a previous step failed silently; building the options map programmatically and omitting latest when a baseline exists.

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

• baseline image is not a valid image
• cache() requires (key, fn)
• context.get() requires a name argument
• context.getGlobal() requires a name argument
• context.set() requires a name argument

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

Appendix: source

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

        }
        if (args.length > 1) {
            out.put("latest", args[1]);
        }
        if (args.length > 2 && args[2] instanceof Map<?, ?> opts) {
            opts.forEach((k, v) -> out.put(String.valueOf(k), v));
        }
        return out;
    }

    private static boolean looksLikePath(String s) {
        return s.startsWith(Resource.THIS_COLON) || s.startsWith("classpath:") || s.startsWith("file:")
                || s.indexOf('/') >= 0 || s.indexOf('\\') >= 0;
    }

    private byte[] requireLatest(Map<String, Object> call) {
        byte[] latest = toBytes(call.get("latest"));
        if (latest == null) {
            throw new RuntimeException("image.diff: 'latest' image (bytes or path) is required");
        }
        return latest;
    }

    private byte[] toBytes(Object o) {
        if (o == null) {
            return null;
        }
        if (o instanceof byte[] b) {
            return b;
        }
        if (o instanceof io.karatelabs.js.JsValue jv) {
            return toBytes(jv.getJavaValue());
        }
        if (o instanceof String s) {
            return readBytes(s);
        }
        throw new RuntimeException("image: unsupported image value " + o.getClass().getName()

View on GitHub (pinned to a22eb90246)