{"record":{"id":"08e210aa757e6bf2","repo":"karatelabs/karate","slug":"embed-each-part-needs-a-role","errorCode":null,"errorMessage":"embed(): each part needs a 'role'","messagePattern":"embed\\(\\): each part needs a 'role'","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java","lineNumber":530,"sourceCode":"                    ? args[1].toString() : KarateJsUtils.detectMimeType(first);\n            String name = args.length > 2 ? args[2].toString() : null;\n            byte[] data = KarateJsUtils.convertToBytes(first);\n            LogContext.get().embed(data, mimeType, name);\n            return null;\n        };\n    }\n\n    private StepResult.Embed toMultiPartEmbed(Map<?, ?> map) {\n        String name = map.get(\"name\") != null ? map.get(\"name\").toString() : null;\n        List<StepResult.Part> parts = new ArrayList<>();\n        for (Object partObj : (List<?>) map.get(\"parts\")) {\n            Object pu = unwrapJs(partObj);\n            if (!(pu instanceof Map<?, ?> pm)) {\n                throw new RuntimeException(\"embed(): each 'parts' entry must be an object\");\n            }\n            Object roleObj = pm.get(\"role\");\n            if (roleObj == null) {\n                throw new RuntimeException(\"embed(): each part needs a 'role'\");\n            }\n            String role = roleObj.toString();\n            String mime = pm.get(\"mime\") != null ? pm.get(\"mime\").toString() : null;\n            Object url = pm.get(\"url\");\n            if (url != null) {\n                parts.add(new StepResult.Part(role, mime, url.toString()));\n                continue;\n            }\n            byte[] bytes;\n            Object dataObj = pm.get(\"data\");\n            Object pathObj = pm.get(\"path\");\n            if (dataObj != null) {\n                bytes = KarateJsUtils.convertToBytes(unwrapJs(dataObj));\n            } else if (pathObj != null) {\n                bytes = readPathBytes(pathObj.toString());\n            } else {\n                throw new RuntimeException(\"embed(): part '\" + role + \"' needs 'data', 'path', or 'url'\");\n            }","sourceCodeStart":512,"sourceCodeEnd":548,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java#L512-L548","documentation":"Validation in toMultiPartEmbed, the map-form of embed(): every entry in the 'parts' list must carry a 'role' key so the multipart body part can be classified (e.g. form-field vs file). Fires when a part object omits 'role'; add a role to each part.","triggerScenarios":"karate.embed({parts: [{path: 'a.png'}]}) or parts objects built dynamically where role was omitted or set to null.","commonSituations":"Hand-writing embed payloads and forgetting role; dynamic part construction where the role variable was undefined; migrating single embeds to multipart form without adding roles.","solutions":["Add a role string to every part object: {role: 'screenshot', path: 'a.png'}.","Ensure the role value is not JS null/undefined at build time.","Keep roles descriptive and consistent across steps for readable reports."],"exampleFix":"// before\nkarate.embed({ parts: [{ path: 'a.png' }] });\n\n// after\nkarate.embed({ parts: [{ role: 'screenshot', path: 'a.png' }] });","handlingStrategy":"validation","validationCode":"if (parts.some(function(p){ return p == null || p.role == null; })) { throw new Error('each part needs a role'); }","typeGuard":"function hasRole(p) { return p != null && typeof p === 'object' && typeof p.role === 'string' && p.role.length > 0; }","tryCatchPattern":"try { karate.embed({ parts: parts }); } catch (e) { if (String(e.message).includes(\"needs a 'role'\")) { karate.log('part missing role'); } throw e; }","preventionTips":["Give every part a descriptive role string","Check role variables are set when building parts dynamically","Standardize role names across your project's reporting"],"tags":["javascript","validation","embed","reporting","karate"],"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"}