{"record":{"id":"c332b829dff0bc06","repo":"karatelabs/karate","slug":"image-diff-latest-image-bytes-or-path-is-required","errorCode":null,"errorMessage":"image.diff: 'latest' image (bytes or path) is required","messagePattern":"image\\.diff: 'latest' image \\(bytes or path\\) is required","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java","lineNumber":508,"sourceCode":"        }\n        if (args.length > 1) {\n            out.put(\"latest\", args[1]);\n        }\n        if (args.length > 2 && args[2] instanceof Map<?, ?> opts) {\n            opts.forEach((k, v) -> out.put(String.valueOf(k), v));\n        }\n        return out;\n    }\n\n    private static boolean looksLikePath(String s) {\n        return s.startsWith(Resource.THIS_COLON) || s.startsWith(\"classpath:\") || s.startsWith(\"file:\")\n                || s.indexOf('/') >= 0 || s.indexOf('\\\\') >= 0;\n    }\n\n    private byte[] requireLatest(Map<String, Object> call) {\n        byte[] latest = toBytes(call.get(\"latest\"));\n        if (latest == null) {\n            throw new RuntimeException(\"image.diff: 'latest' image (bytes or path) is required\");\n        }\n        return latest;\n    }\n\n    private byte[] toBytes(Object o) {\n        if (o == null) {\n            return null;\n        }\n        if (o instanceof byte[] b) {\n            return b;\n        }\n        if (o instanceof io.karatelabs.js.JsValue jv) {\n            return toBytes(jv.getJavaValue());\n        }\n        if (o instanceof String s) {\n            return readBytes(s);\n        }\n        throw new RuntimeException(\"image: unsupported image value \" + o.getClass().getName()","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java#L490-L526","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Add a non-null 'latest' value: image.diff({ baseline: 'base.png', latest: 'latest.png' })","Pass the latest image as a path string, byte[], or Uint8Array to image.diff(name, latest)","Log/verify the latest variable in JS before calling diff (it must be defined)","Check for key typos: the key must be exactly 'latest'"],"exampleFix":"// before\nimage.diff({ baseline: 'base.png' }) // missing latest\n// after\nimage.diff({ baseline: 'base.png', latest: 'latest.png' })","handlingStrategy":"validation","validationCode":"// JS before calling diff\nkarate.log('latest value:', latest);\nif (latest == null) karate.fail(\"'latest' image is required before image.diff\");\nimage.diff({ baseline: 'base.png', latest: latest });","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass 'latest' explicitly in the diff map rather than relying on overloads","Define the screenshot variable in the same scenario before diffing","Keep the map key spelled exactly 'latest'"],"tags":["image","missing-argument","visual-testing"],"backgroundTag":"missing-required-argument","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}