{"record":{"id":"51f699ab44693817","repo":"karatelabs/karate","slug":"headers-needs-a-map-argument","errorCode":null,"errorMessage":"headers() needs a map argument","messagePattern":"headers\\(\\) needs a map argument","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/http/HttpRequestBuilder.java","lineNumber":767,"sourceCode":"                if (v instanceof List<?> list) {\n                    for (Object item : list) {\n                        if (item != null) {\n                            param(k + \"\", item + \"\");\n                        }\n                    }\n                } else if (v != null) {\n                    param(k + \"\", v + \"\");\n                }\n            });\n            return this;\n        };\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private JavaInvokable headers() {\n        return args -> {\n            if (args.length == 0 || !(args[0] instanceof Map<?, ?> map)) {\n                throw new RuntimeException(\"headers() needs a map argument\");\n            }\n            headers((Map<String, Object>) map);\n            return this;\n        };\n    }\n\n    private JavaInvokable path() {\n        return args -> {\n            for (Object arg : args) {\n                if (arg != null) {\n                    path(arg + \"\");\n                }\n            }\n            return this;\n        };\n    }\n\n    private JavaInvokable body() {","sourceCodeStart":749,"sourceCodeEnd":785,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/http/HttpRequestBuilder.java#L749-L785","documentation":"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.","triggerScenarios":"`headers()` with no args; `headers('Authorization: Bearer x')` passing a raw header string; passing an array of header pairs instead of an object.","commonSituations":"Copy-pasting curl-style header strings into headers(); migrating from APIs that accepted variadic name/value arguments; dynamically computed headers returning null or undefined.","solutions":["Pass a single object: `headers({ Authorization: 'Bearer ' + token })`.","Use `header(name, value)` for individual headers.","Convert arrays of pairs: build `{}` and assign each key before calling headers().","Guard: `if (h && typeof h === 'object' && !Array.isArray(h)) headers(h)`.­"],"exampleFix":"// before\nheaders('Content-Type: application/json')\n// after\nheaders({ 'Content-Type': 'application/json' })","handlingStrategy":"validation","validationCode":"if (h && typeof h === 'object' && !Array.isArray(h)) builder.headers(h); else throw new Error('headers expects a map');","typeGuard":"function isHeaderMap(v) { return v != null && typeof v === 'object' && !Array.isArray(v); }","tryCatchPattern":"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; }","preventionTips":["Pass object literals: { 'Name': 'value' }","Parse raw header strings into objects before calling headers()","Prefer header(name, value) for one-off headers"],"tags":["http","headers","argument-validation"],"backgroundTag":"invalid-argument-value","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"}