{"record":{"id":"a14965b3fc3e7ad0","repo":"karatelabs/karate","slug":"image-unsupported-image-value-classname-expected-a","errorCode":null,"errorMessage":"image: unsupported image value {className} (expected a Uint8Array, byte[], or a path string)","messagePattern":"image: unsupported image value (.+?) \\(expected a Uint8Array, byte\\[\\], or a path string\\)","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java","lineNumber":526,"sourceCode":"            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()\n                + \" (expected a Uint8Array, byte[], or a path string)\");\n    }\n\n    /** A base64 {@code data:} URL for raw image bytes (mime sniffed; for client-side re-diff). */\n    private static String dataUrl(byte[] b) {\n        return \"data:\" + sniffMime(b) + \";base64,\" + java.util.Base64.getEncoder().encodeToString(b);\n    }\n\n    private static String sniffMime(byte[] b) {\n        if (b != null && b.length >= 4) {\n            int b0 = b[0] & 0xFF, b1 = b[1] & 0xFF, b2 = b[2] & 0xFF, b3 = b[3] & 0xFF;\n            if (b0 == 0x89 && b1 == 'P' && b2 == 'N' && b3 == 'G') return \"image/png\";\n            if (b0 == 0xFF && b1 == 0xD8 && b2 == 0xFF) return \"image/jpeg\";\n            if (b0 == 'G' && b1 == 'I' && b2 == 'F' && b3 == '8') return \"image/gif\";\n            if (b0 == 'B' && b1 == 'M') return \"image/bmp\";\n        }\n        return \"image/png\";\n    }","sourceCodeStart":508,"sourceCodeEnd":544,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-image/src/main/java/io/karatelabs/ext/image/ImageApi.java#L508-L544","documentation":"toBytes() normalizes any image argument (latest, baseline) into raw bytes. It accepts a Uint8Array (via JsValue), a Java byte[], or a String treated as a file path. Any other type (Number, Map, JSON object, boolean, etc.) is rejected with this error, because the API cannot interpret it as image content.","triggerScenarios":"Passing a value of unsupported type as an image argument: a JS object/JSON map, a number, a Response object, a base64 string not prefixed as a path, or the result of a step that returned an object instead of bytes/path.","commonSituations":"Storing image bytes in a JSON variable and passing the whole JSON instead of the byte field; passing a JS Number read from a file; accidentally passing the options map as the image argument; migrating tests where the previous API accepted base64 strings directly.","solutions":["Pass the image as a path string, e.g. image.diff({ baseline: 'base.png', latest: 'shot.png' })","If you have bytes, pass the actual byte[]/Uint8Array, not a wrapper object","Unwrap the value: if it is a JSON object, extract the byte field before calling diff","Check that the JS variable is not undefined-object; log its type before the call"],"exampleFix":"// before\nconst img = { data: karate.readBytes('shot.png') }\nimage.diff({ latest: img }) // unsupported: Map\n// after\nimage.diff({ latest: karate.readBytes('shot.png') })","handlingStrategy":"type-guard","validationCode":"// JS: ensure the value is a string path or byte-like before diff\nif (typeof latest !== 'string' && !(latest instanceof Array) && !latest.byteLength) {\n    karate.fail('latest must be a path string or bytes, got: ' + typeof latest);\n}","typeGuard":"function isImageValue(o) {\n  return typeof o === 'string'\n      || (o instanceof Uint8Array)\n      || (Array.isArray(o)); // byte[] via JS array\n}","tryCatchPattern":null,"preventionTips":["Pass image args only as path strings, byte[], or Uint8Array","Never pass JSON maps/Response objects directly as images","Unwrap nested objects to the raw bytes field before calling the API"],"tags":["image","type-mismatch","argument-validation"],"backgroundTag":"type-mismatch","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"}