{"record":{"id":"0afc7bb0694ffb21","repo":"karatelabs/karate","slug":"image-diff-need-a-name-or-a-baseline-and-a-latest","errorCode":null,"errorMessage":"image.diff: need a name or a baseline (and a latest)","messagePattern":"image\\.diff: need a name or a baseline \\(and a latest\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java","lineNumber":146,"sourceCode":"        Object baselineArg = call.get(\"baseline\");\n        String baselinePath = null;\n        String optionsPath = null;\n        byte[] baseline;\n\n        Map<String, Object> options = new LinkedHashMap<>();\n        if (baselineArg instanceof String s) {\n            baselinePath = absolute(s);          // explicit path: no <name>.json auto-load\n            baseline = readBytes(s);\n        } else if (baselineArg != null) {\n            baseline = toBytes(baselineArg);     // explicit baseline bytes / Uint8Array\n        } else if (name != null) {\n            Map<String, Object> resolved = resolve(name);\n            baselinePath = str(resolved.get(\"baselinePath\"));\n            optionsPath = str(resolved.get(\"optionsPath\"));\n            options.putAll(loadOptionsFile(optionsPath));   // file opts: low precedence\n            baseline = readBytes(baselinePath);\n        } else {\n            throw new RuntimeException(\"image.diff: need a name or a baseline (and a latest)\");\n        }\n\n        // per-call inline options (everything that isn't structural) override the file\n        for (Map.Entry<String, Object> e : call.entrySet()) {\n            if (!STRUCTURAL.contains(e.getKey())) {\n                options.put(e.getKey(), e.getValue());\n            }\n        }\n        if (options.containsKey(\"threshold\")) {\n            options.put(\"failureThreshold\", options.remove(\"threshold\"));\n        }\n        String reportName = name != null ? name : str(options.get(\"name\"));\n        if (reportName != null) {\n            options.put(\"name\", reportName);\n        }\n\n        Map<String, Object> r = ImageComparison.run(baseline, latest, options, defaultOptions());\n        return result(r, reportName, options, baseline, latest, baselinePath, optionsPath);","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java#L128-L164","documentation":"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.","triggerScenarios":"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.","commonSituations":"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').","solutions":["Pass a name that was previously established: { name: 'screenshot-home' }","Or pass explicit images: { baseline: <bytes>, latest: <bytes> }","Call image.write with the baseline first so the name resolves to a baselinePath","Verify the argument keys are exactly 'name', 'baseline', 'latest'"],"exampleFix":"// before\nkarate.call('image.diff', { fuzzy: 0.1 }); // no name/baseline\n// after\nkarate.call('image.diff', { name: 'screenshot-home', fuzzy: 0.1 });","handlingStrategy":"validation","validationCode":"# karate\n* if (!args.name && !(args.baseline && args.latest)) karate.abort('image.diff needs name or baseline+latest')","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Always establish baselines with image.write before diffing by name","Use exact key names: 'name', 'baseline', 'latest'","Wrap diff calls in a helper that validates args first"],"tags":["karate","image-comparison","missing-argument"],"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-16T19:17:19.609Z"}