{"record":{"id":"b9cfba8b3778b5f8","repo":"karatelabs/karate","slug":"params-needs-a-map-argument","errorCode":null,"errorMessage":"params() needs a map argument","messagePattern":"params\\(\\) needs a map argument","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/http/HttpRequestBuilder.java","lineNumber":746,"sourceCode":"        return args -> {\n            if (args.length < 2) {\n                throw new RuntimeException(\"param() needs two arguments\");\n            }\n            param(args[0] + \"\", args[1] + \"\");\n            return this;\n        };\n    }\n\n    /**\n     * The JS-facing plural forms of {@link #param} and {@link #header}. The Java\n     * {@link #params(Map)} takes a {@code Map<String, List<String>>} and replaces what was\n     * there, which is awkward to satisfy from JS - these accumulate and accept a scalar or a\n     * list per key, matching the {@code params} and {@code headers} keywords.\n     */\n    private JavaInvokable params() {\n        return args -> {\n            if (args.length == 0 || !(args[0] instanceof Map<?, ?> map)) {\n                throw new RuntimeException(\"params() needs a map argument\");\n            }\n            map.forEach((k, v) -> {\n                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() {","sourceCodeStart":728,"sourceCodeEnd":764,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/http/HttpRequestBuilder.java#L728-L764","documentation":"karate's params() JS helper on HttpRequestBuilder only accepts a single Map argument (matching the `param` keyword semantics: scalar or list values per key). The library throws this RuntimeException when params() is called with no arguments or with a non-Map first argument, because there is no meaningful interpretation of other inputs.","triggerScenarios":"Calling `params()` with zero arguments, or `params('a=1')`, `params([['a','b']])`, or any string/list/scalar instead of a JS object like `params({a: '1'})`.","commonSituations":"Porting from older Karate DSL where params took key/value pairs; passing a URL-encoded query string instead of a map; forgetting the argument entirely in a JS `configure` or request block.","solutions":["Pass a single map argument: `params({ page: 1, tag: ['x','y'] })`.","If you have key/value pairs, build a map first: `params({ [k]: v })` or collect into an object.","Use `param(name, value)` for one-off additions instead of params().","Wrap dynamic inputs with a check: `if (q && typeof q === 'object' && !Array.isArray(q)) params(q)`.­"],"exampleFix":"// before\nparams('page=1&size=10')\n// after\nparams({ page: 1, size: 10 })","handlingStrategy":"validation","validationCode":"function safeParams(builder, m) { if (m && typeof m === 'object' && !Array.isArray(m)) builder.params(m); return builder; }","typeGuard":"function isPlainMap(v) { return v != null && typeof v === 'object' && !Array.isArray(v); }","tryCatchPattern":"try { builder.params(q); } catch (e) { if (('' + e).includes('needs a map argument')) builder.param('raw', String(q)); else throw e; }","preventionTips":["Always pass a JS object literal to params()","Never pass URL-encoded query strings — build the map instead","Use param(name, value) for single dynamic additions"],"tags":["http","argument-validation","javascript"],"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"}