{"record":{"id":"50bc0f15658bed86","repo":"karatelabs/karate","slug":"multipart-fields-expects-a-map","errorCode":null,"errorMessage":"multipart fields expects a map: ","messagePattern":"multipart fields expects a map: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/StepExecutor.java","lineNumber":2519,"sourceCode":"    @SuppressWarnings(\"unchecked\")\n    private void executeMultipartFields(Step step) {\n        Object value = evalKarateExpression(step.getText());\n        if (value instanceof Map) {\n            Map<String, Object> fields = (Map<String, Object>) value;\n            for (Map.Entry<String, Object> entry : fields.entrySet()) {\n                Map<String, Object> multipartMap = new HashMap<>();\n                multipartMap.put(\"name\", entry.getKey());\n                Object fieldValue = entry.getValue();\n                if (fieldValue instanceof Map) {\n                    // V1 behavior: merge map fields (e.g., { value: 'x', contentType: 'y' })\n                    multipartMap.putAll((Map<String, Object>) fieldValue);\n                } else {\n                    multipartMap.put(\"value\", fieldValue);\n                }\n                http().multiPart(multipartMap);\n            }\n        } else {\n            throw new RuntimeException(\"multipart fields expects a map: \" + step.getText());\n        }\n    }\n\n    /**\n     * Handles: multipart files [{ read: 'file1.txt', name: 'file1' }, { read: 'file2.txt', name: 'file2' }]\n     * Also handles V1 map syntax: multipart files { myFile1: {...}, myFile2: {...} }\n     * where map keys become the part names.\n     */\n    @SuppressWarnings(\"unchecked\")\n    private void executeMultipartFiles(Step step) {\n        Object value = evalKarateExpression(step.getText());\n        if (value instanceof List) {\n            List<Object> files = (List<Object>) value;\n            for (Object item : files) {\n                processMultipartFileEntry(item, null);\n            }\n        } else if (value instanceof Map) {\n            // V1 compatibility: map where keys are part names","sourceCodeStart":2501,"sourceCodeEnd":2537,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/StepExecutor.java#L2501-L2537","documentation":"The `multipart fields <expr>` step evaluates an expression that must yield a Map of field name to value. If the evaluated result is not a Map, StepExecutor throws this RuntimeException including the step text.","triggerScenarios":"`multipart fields` with an expression evaluating to a list, string, or null — e.g. passing a JSON array, a scalar, or a function call returning the wrong shape.","commonSituations":"Reusing a variable intended for `multipart files` (a list) in `multipart fields`; an eval producing null because a JSON path missed; typos in variable names.","solutions":["Ensure the expression evaluates to a JSON object/map: `multipart fields { field1: 'value1', field2: '#(var)' }`.","Print the value first (`* print myFields`) and confirm it is a map.","If your data is a list, switch to the `multipart files` step.","Fix the variable/expression so it doesn't resolve to null or a scalar."],"exampleFix":"// before\n* def fields = [{ name: 'a' }]\nAnd multipart fields fields\n// after\n* def fields = { a: 'valueA', b: 'valueB' }\nAnd multipart fields fields","handlingStrategy":"type-guard","validationCode":"// Guard before the step\n* def fields = myFields || {}\n* assert typeof fields == 'map'\nAnd multipart fields fields","typeGuard":"function isNonEmptyMap(v) { return v != null && typeof v === 'object' && !Array.isArray(v); }","tryCatchPattern":"try { scenario.run(step) } catch (RuntimeException e) { if (e.getMessage().startsWith(\"multipart fields expects a map\")) { /* eval the expression and verify it's a map */ } throw e; }","preventionTips":["Print the evaluated variable before the step to confirm shape.","Don't reuse `multipart files` (list) data in `multipart fields`.","Default null-eval results to `{}` upstream.","Keep helper functions that build field maps returning plain objects."],"tags":["karate","multipart","type-mismatch","http"],"backgroundTag":"type-mismatch","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"}