karatelabs/karate · error · RuntimeException

multipart field requires '=' assignment:

Error message

multipart field requires '=' assignment: 

What it means

The `multipart field <name> = <value>` step requires an `=` assignment between the field name and its value expression. StepExecutor's assignment-operator search failed, so it throws a RuntimeException containing the raw step text.

Solutions

1. Write `multipart field foo = 'value'` exactly, with `=` between name and value.
2. Check that the field name itself doesn't confuse the parser (avoid stray characters).
3. For many fields, use `multipart fields { foo: 'bar', baz: 'qux' }` instead of individual lines.
4. Consult the docs for the exact multipart field grammar.

Example fix

// before
And multipart field description 'hello'
// after
And multipart field description = 'hello'

// Confirm the step has name = value form
* assert 'multipart field desc'.indexOf('=') >= 0 || 'add = value'

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

When it happens

Trigger: Writing `multipart field foo` without a value, or malformed text where `StepUtils.findAssignmentOperator` cannot locate `=` (e.g. `multipart field foo 'bar'` using a space instead of `=`).

Common situations: Hand-writing multipart forms from memory; migrating from syntaxes that used different separators; copy-paste errors dropping `= 'value'`.

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 file 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/388cf56843742aa2. Report an issue: GitHub.

Appendix: source

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

            // Direct string value - could be file path or content
            multipartMap.put("value", value);
        } else if (value instanceof byte[]) {
            multipartMap.put("value", value);
        } else {
            multipartMap.put("value", value);
        }

        http().multiPart(multipartMap);
    }

    /**
     * Handles: multipart field name = 'value'
     */
    private void executeMultipartField(Step step) {
        String text = step.getText();
        int eqIndex = StepUtils.findAssignmentOperator(text);
        if (eqIndex < 0) {
            throw new RuntimeException("multipart field requires '=' assignment: " + text);
        }
        String name = text.substring(0, eqIndex).trim();
        String expr = text.substring(eqIndex + 1).trim();

        Object value = runtime.eval(wrapJsonLikeExpression(expr));

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

        http().multiPart(multipartMap);
    }

    /**
     * Handles: multipart fields { name: 'value', other: 'data' }
     * V1 behavior: if field value is a map with 'value' key, merge it (not nest it)
     */
    @SuppressWarnings("unchecked")

View on GitHub (pinned to a22eb90246)