{"record":{"id":"9261e7f82e0e6baa","repo":"karatelabs/karate","slug":"multipart-files-entry-must-be-a-map","errorCode":null,"errorMessage":"multipart files entry must be a map: ","messagePattern":"multipart files entry must be a map: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/StepExecutor.java","lineNumber":2589,"sourceCode":"                    } catch (Exception e) {\n                        throw new RuntimeException(\"failed to read file: \" + readPath, e);\n                    }\n                }\n            } else if (fileMap.get(\"value\") != null) {\n                multipartMap.put(\"value\", fileMap.get(\"value\"));\n            }\n\n            // Copy other properties\n            if (fileMap.get(\"filename\") != null) {\n                multipartMap.put(\"filename\", fileMap.get(\"filename\"));\n            }\n            if (fileMap.get(\"contentType\") != null) {\n                multipartMap.put(\"contentType\", fileMap.get(\"contentType\"));\n            }\n\n            http().multiPart(multipartMap);\n        } else {\n            throw new RuntimeException(\"multipart files entry must be a map: \" + item);\n        }\n    }\n\n    /**\n     * Handles: multipart entity value\n     * For sending a single entity as the multipart body (advanced use case)\n     */\n    @SuppressWarnings(\"unchecked\")\n    private void executeMultipartEntity(Step step) {\n        String expr = step.getDocString() != null ? step.getDocString() : step.getText();\n        Object value = evalKarateExpression(expr);\n\n        if (value instanceof Map) {\n            // Single entity map with name, value, etc.\n            http().multiPart((Map<String, Object>) value);\n        } else {\n            // Wrap in a default map\n            Map<String, Object> multipartMap = new HashMap<>();","sourceCodeStart":2571,"sourceCodeEnd":2607,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/StepExecutor.java#L2571-L2607","documentation":"Karate's multipart 'files' keyword expects each entry in the files collection to be a Map describing the file to upload (e.g. with 'read', 'name', 'filename', 'contentType' keys). When an entry is not a Map (a bare string, list, number, etc.), StepExecutor cannot convert it into the internal multiPart structure and throws this RuntimeException naming the offending item. It is a fail-fast argument-shape validation inside multipart request construction.","triggerScenarios":"Using `* multipart file foo` where the variable `foo` holds a plain string path, JSON array, or other non-map value instead of a map like {read: 'file.txt', name: 'file'}; passing an entry of a files list that was built dynamically and ended up as a non-map element.","commonSituations":"Copying Karate 0.x/1.x string-style multipart syntax (`multipart file myFile = 'path.txt'`) into this engine, which expects map entries; building files entries in JS and forgetting the map wrapper; typos where a variable resolves to the wrong type.","solutions":["Wrap each multipart files entry in a map with at least a 'read' key: { read: '#(path)', name: 'file' }","Log the variable with print before the multipart call to confirm its type","If uploading by path string, construct the map explicitly rather than passing the raw string","Check whether an earlier step overwrote the variable with a scalar value"],"exampleFix":"// before\n* def myFile = 'upload.png'\n* multipart file myFile\n// after\n* def myFile = { read: 'upload.png', name: 'file' }\n* multipart file myFile","handlingStrategy":"validation","validationCode":"// karate\n* if (!myFile.__proto__ === {}.constructor) karate.fail('multipart files entry must be a map')\n// or in JS: karate.match('myFile.#(map)', true)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always define multipart entries as maps with a 'read' key","print the entry variable before multipart steps","Keep file upload fixtures in a shared def block reviewed for shape"],"tags":["multipart","type-mismatch","http"],"backgroundTag":"invalid-argument-format","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"}