karatelabs/karate · error · RuntimeException

multipart files entry requires 'name':

Error message

multipart files entry requires 'name': 

What it means

Each entry in a `multipart files` list/map must identify its part name — either as the map-entry key (V1 style) or a `name` property in the entry object. When a list entry lacks both, StepExecutor throws this RuntimeException showing the offending entry.

Solutions

1. Add `name` to each entry: `{ name: 'myFile', read: 'file.txt' }`.
2. Or use the V1 map form where the key is the name: `{ myFile: { read: 'file.txt' } }`.
3. Validate generated entries include `name` before invoking the step.
4. Include `filename` too if the server expects an original filename.

Example fix

// before
And multipart files [{ read: 'data/a.txt' }]
// after
And multipart files [{ name: 'uploadA', read: 'data/a.txt', filename: 'a.txt' }]

// Validate every entry has a name before the step
* def entries = [{ read: 'a.txt' }]
* def ok = karate.size(entries.filter(function(e){ return e.name == null })) == 0
* assert ok

function hasName(e) { return e != null && (e.name != null || typeof e === 'object' && Object.keys(e).length > 0); }

try { scenario.run(step) } catch (RuntimeException e) { if (e.getMessage().startsWith("multipart files entry requires 'name'")) { /* add name or use map-key form */ } throw e; }

When it happens

Trigger: `multipart files [{ read: 'file.txt' }, ...]` — list items without a `name` property and no default name from a map key.

Common situations: Converting from V1 map syntax to list syntax and dropping the `name` key; assuming the filename inside `read` implies the part name; programmatically generated entries missing the field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• multipart file requires '=' assignment:
• multipart field requires '=' assignment:
• multipart fields expects a map:
• multipart files expects a list or map:
• embed(): each 'parts' entry must be an object

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/48659da51a77a762. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/StepExecutor.java:2556

            Map<String, Object> filesMap = (Map<String, Object>) value;
            for (Map.Entry<String, Object> entry : filesMap.entrySet()) {
                processMultipartFileEntry(entry.getValue(), entry.getKey());
            }
        } else {
            throw new RuntimeException("multipart files expects a list or map: " + step.getText());
        }
    }

    private void processMultipartFileEntry(Object item, String defaultName) {
        if (item instanceof Map) {
            @SuppressWarnings("unchecked")
            Map<String, Object> fileMap = (Map<String, Object>) item;
            Map<String, Object> multipartMap = new HashMap<>();

            // Name from map entry key (V1 compat) or from 'name' property
            String name = defaultName != null ? defaultName : (String) fileMap.get("name");
            if (name == null) {
                throw new RuntimeException("multipart files entry requires 'name': " + item);
            }
            multipartMap.put("name", name);

            // Handle file read
            Object readPath = fileMap.get("read");
            if (readPath != null) {
                Resource resource = resolveResource(readPath.toString());
                File file = getFileFromResource(resource);
                if (file != null) {
                    multipartMap.put("value", file);
                } else {
                    try (InputStream is = resource.getStream()) {
                        byte[] bytes = is.readAllBytes();
                        multipartMap.put("value", bytes);
                    } catch (Exception e) {
                        throw new RuntimeException("failed to read file: " + readPath, e);
                    }
                }

View on GitHub (pinned to a22eb90246)