karatelabs/karate · error · RuntimeException

headers() needs a map argument

Error message

headers() needs a map argument

What it means

headers() on HttpRequestBuilder accepts exactly one Map argument whose entries become request headers, mirroring the `headers` keyword. The library throws when called with no arguments or a non-Map argument, since per-key list/scalar coercion is defined only for maps.

Solutions

1. Pass a single object: `headers({ Authorization: 'Bearer ' + token })`.
2. Use `header(name, value)` for individual headers.
3. Convert arrays of pairs: build `{}` and assign each key before calling headers().
4. Guard: `if (h && typeof h === 'object' && !Array.isArray(h)) headers(h)`.­

Example fix

// before
headers('Content-Type: application/json')
// after
headers({ 'Content-Type': 'application/json' })

if (h && typeof h === 'object' && !Array.isArray(h)) builder.headers(h); else throw new Error('headers expects a map');

function isHeaderMap(v) { return v != null && typeof v === 'object' && !Array.isArray(v); }

try { builder.headers(h); } catch (e) { if (('' + e).includes('needs a map argument')) { Object.entries(parseHeaderString(h)).forEach(([k, v]) => builder.header(k, v)); } else throw e; }

When it happens

Trigger: `headers()` with no args; `headers('Authorization: Bearer x')` passing a raw header string; passing an array of header pairs instead of an object.

Common situations: Copy-pasting curl-style header strings into headers(); migrating from APIs that accepted variadic name/value arguments; dynamically computed headers returning null or undefined.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• missing argument for header()
• missing argument for headerValues()
• header() needs two arguments
• params() needs a map argument
• body() needs at least one argument

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/HttpRequestBuilder.java:767

                if (v instanceof List<?> list) {
                    for (Object item : list) {
                        if (item != null) {
                            param(k + "", item + "");
                        }
                    }
                } else if (v != null) {
                    param(k + "", v + "");
                }
            });
            return this;
        };
    }

    @SuppressWarnings("unchecked")
    private JavaInvokable headers() {
        return args -> {
            if (args.length == 0 || !(args[0] instanceof Map<?, ?> map)) {
                throw new RuntimeException("headers() needs a map argument");
            }
            headers((Map<String, Object>) map);
            return this;
        };
    }

    private JavaInvokable path() {
        return args -> {
            for (Object arg : args) {
                if (arg != null) {
                    path(arg + "");
                }
            }
            return this;
        };
    }

    private JavaInvokable body() {

View on GitHub (pinned to a22eb90246)