karatelabs/karate · error · RuntimeException

multipart file requires '=' assignment:

Error message

multipart file requires '=' assignment: 

What it means

The `multipart file <name> = <expr>` step requires an `=` assignment separating the part name from its value expression. StepExecutor could not find an assignment operator in the step text, so it throws a RuntimeException with the offending text.

Solutions

1. Write the step as `multipart file myFile = { read: 'file.txt' }` with name, `=`, and value.
2. Check for typos that removed or misplaced the `=`.
3. For inline file bytes use `multipart file myFile = read('file.txt')`.
4. For multiple parts or non-assignment shapes, use `multipart files` with a list/map instead.

Example fix

// before
And multipart file myFile
// after
And multipart file myFile = { read: 'data/file.txt', filename: 'file.txt', contentType: 'text/plain' }

// Ensure the step text has an '=' assignment before running
* def stepText = 'multipart file myFile'
* assert stepText.contains('=') || 'use the correct step syntax'

try { scenario.run(step) } catch (RuntimeException e) { if (e.getMessage().startsWith("multipart file requires '='")) { /* fix feature syntax */ } throw e; }

When it happens

Trigger: Writing `multipart file myFile` (no `= value`), or using syntax the assignment finder doesn't recognize (e.g. missing space or malformed expression).

Common situations: Porting V1 scripts with different multipart syntax; typos like `multipart file = myFile` (missing name); copy-paste dropping the value side of the assignment.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• multipart field requires '=' assignment:
• multipart fields expects a map:
• multipart files expects a list or map:
• multipart files entry requires 'name':
• unknown keyword

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

Appendix: source

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

    private void executeStatus(Step step) {
        int expected = Integer.parseInt(step.getText().trim());
        Object statusObj = runtime.getVariable("responseStatus");
        int actual = statusObj instanceof Number n ? n.intValue() : Integer.parseInt(statusObj.toString());
        if (actual != expected) {
            throw new AssertionError("expected status: " + expected + ", actual: " + actual);
        }
    }

    /**
     * Handles: multipart file myFile = { read: 'file.txt', filename: 'test.txt', contentType: 'text/plain' }
     * Or shorthand: multipart file myFile = read('file.txt')
     */
    @SuppressWarnings("unchecked")
    private void executeMultipartFile(Step step) {
        String text = step.getText();
        int eqIndex = StepUtils.findAssignmentOperator(text);
        if (eqIndex < 0) {
            throw new RuntimeException("multipart file requires '=' assignment: " + text);
        }
        String name = text.substring(0, eqIndex).trim();
        String expr = text.substring(eqIndex + 1).trim();

        Object value = evalKarateExpression(expr);

        Map<String, Object> multipartMap = new HashMap<>();
        multipartMap.put("name", name);

        if (value instanceof Map) {
            Map<String, Object> fileMap = (Map<String, Object>) value;
            // Handle { read: 'path', filename: 'name', contentType: 'type' }
            Object readPath = fileMap.get("read");
            if (readPath != null) {
                Resource resource = resolveResource(readPath.toString());
                File file = getFileFromResource(resource);
                if (file != null) {
                    multipartMap.put("value", file);

View on GitHub (pinned to a22eb90246)