{"record":{"id":"3311740b455a5149","repo":"karatelabs/karate","slug":"multipart-files-expects-a-list-or-map","errorCode":null,"errorMessage":"multipart files expects a list or map: ","messagePattern":"multipart files expects a list or map: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/StepExecutor.java","lineNumber":2543,"sourceCode":"     * 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\n            Map<String, Object> filesMap = (Map<String, Object>) value;\n            for (Map.Entry<String, Object> entry : filesMap.entrySet()) {\n                processMultipartFileEntry(entry.getValue(), entry.getKey());\n            }\n        } else {\n            throw new RuntimeException(\"multipart files expects a list or map: \" + step.getText());\n        }\n    }\n\n    private void processMultipartFileEntry(Object item, String defaultName) {\n        if (item instanceof Map) {\n            @SuppressWarnings(\"unchecked\")\n            Map<String, Object> fileMap = (Map<String, Object>) item;\n            Map<String, Object> multipartMap = new HashMap<>();\n\n            // Name from map entry key (V1 compat) or from 'name' property\n            String name = defaultName != null ? defaultName : (String) fileMap.get(\"name\");\n            if (name == null) {\n                throw new RuntimeException(\"multipart files entry requires 'name': \" + item);\n            }\n            multipartMap.put(\"name\", name);\n\n            // Handle file read\n            Object readPath = fileMap.get(\"read\");","sourceCodeStart":2525,"sourceCodeEnd":2561,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/StepExecutor.java#L2525-L2561","documentation":"The `multipart files <expr>` step accepts either a List of file-part objects or a Map of part name to part object (V1 compatibility). If the evaluated value is neither, StepExecutor throws this RuntimeException with the step text.","triggerScenarios":"`multipart files` given a scalar, string, or null — e.g. a variable that failed to evaluate, or reusing a plain fields map where values are not file-part objects.","commonSituations":"Confusing `multipart fields` data with `multipart files` data; a JSON path or helper returning null; building the list in JS and returning the wrong type.","solutions":["Pass a list: `multipart files [{ read: 'a.txt', name: 'fileA' }, { read: 'b.txt', name: 'fileB' }]`.","Or a map: `multipart files { fileA: { read: 'a.txt' }, fileB: { read: 'b.txt' } }`.","Print the value before the step to confirm its shape.","Fix the producing expression so it yields a list or map, not null/scalar."],"exampleFix":"// before\n* def f = 'not-a-list'\nAnd multipart files f\n// after\n* def f = [{ name: 'fileA', read: 'data/a.txt' }]\nAnd multipart files f","handlingStrategy":"type-guard","validationCode":"* def files = myFiles || []\n* assert typeof files == 'list' || typeof files == 'map'","typeGuard":"function isFileListOrMap(v) { return v != null && (Array.isArray(v) || typeof v === 'object'); }","tryCatchPattern":"try { scenario.run(step) } catch (RuntimeException e) { if (e.getMessage().startsWith(\"multipart files expects a list or map\")) { /* normalize the value to a list/map first */ } throw e; }","preventionTips":["Always pass a list of part objects or a name-keyed map to `multipart files`.","Wrap expressions that may eval to null with `|| []`.","Distinguish `multipart fields` (map) from `multipart files` (list/map of file parts).","Unit-test JS helpers that generate file-part collections."],"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"}