In REST Assured, why does setting the same custom header twice send two values, and how do you stop it?

## Merge is the default for headers, not overwrite `RequestSpecification.header(name, value)` does not set a slot; it appends an entry to a list of headers. When a second `header("X-Depot-Id", "south-yard")` arrives, REST Assured looks up the name in `HeaderConfig` to decide whether the earlier entry should be discarded. If the configuration says that name overwrites, the earlier entries with that name are dropped; otherwise both survive and the request goes out with two `X-Depot-Id` lines. `HeaderConfig` ships with exactly **two** names marked for overwrite, matched case-insensitively: `content-type` and `accept`. Every other name — including every `X-`-prefixed header a snowplough dispatch API might define — merges. So: - `header("X-Depot-Id", "north-yard").header("X-Depot-Id", "south-yard")` sends both values. - `contentType(ContentType.JSON).contentType(ContentType.XML)` sends only the XML content type. - `accept(ContentType.JSON).accept("text/csv")` sends only `text/csv`. - `header("X-Dispatch-Trace", "a", "b")` — the varargs overload — deliberately records two values under one name in a single call. ## Why this bites in a real suite The two calls are almost never adjacent. The usual shape is a shared `RequestSpecification` that stamps `X-Depot-Id: north-yard` on every request, plus one test that needs the southern depot and sets the header again. Attaching a specification **accumulates** headers rather than replacing them, so the merge default and specification merging point the same way, and the dispatch service sees a header it considers ambiguous. Depending on the service, you get a 400, a silent first-value-wins, or — worst for debugging — a correct-looking response produced from the wrong depot. ## Making a name overwrite ```java given() .config(config().headerConfig(headerConfig().overwriteHeadersWithName("X-Depot-Id"))) .header("X-Depot-Id", "north-yard") .header("X-Depot-Id", "south-yard") .when() .get("/v1/routes"); ``` `overwriteHeadersWithName(String, String...)` takes one name plus any number of extra names and returns a new `HeaderConfig` in which those names replace. Its mirror, `mergeHeadersWithName(String, String...)`, makes the listed names accumulate — which is how you would deliberately send two `Accept` headers if a dispatch endpoint required it. ## The trap inside the switch `HeaderConfig` stores a single map of names to overwrite. `overwriteHeadersWithName(...)` builds a **fresh** map containing only the names you passed — it does not add to the shipped set. So a config built as `headerConfig().overwriteHeadersWithName("X-Depot-Id")` no longer lists `content-type` or `accept`, and those two revert to merging. If you rely on the exception for either, name them explicitly: 1. List every name you want to overwrite in the one call: `overwriteHeadersWithName("X-Depot-Id", "Content-Type", "Accept")`. 2. Or keep the default config and change how the test sets the header instead — for instance by removing the header inside a filter before setting it. 3. Or restructure so the shared specification never sets a header a test needs to override. Option three is usually the healthiest: configuration that silently changes what two other headers do is a poor trade for one overridable name. ## Cookies have no equivalent switch Request cookies always accumulate. `cookie("depot", "north-yard").cookie("depot", "south-yard")` records two cookies, and at send time REST Assured joins every request cookie into a **single** `Cookie` header as `name=value` pairs separated by `"; "`, in insertion order — so the dispatch service receives `Cookie: depot=north-yard; depot=south-yard`. There is no `CookieConfig` update strategy to flip: - `cookie(String, Object, Object...)` adds one entry per value. - `cookies(Map)` and `cookies(Cookies)` append to whatever is already recorded. - The only way to end up with one cookie of a given name is not to record the other one. | what you set twice | what the dispatch API receives | |---|---| | `header("X-Depot-Id", ...)` | two `X-Depot-Id` header lines | | `contentType(...)` | one `Content-Type`, the later value | | `accept(...)` | one `Accept`, the later value | | `cookie("depot", ...)` | one `Cookie` header carrying both pairs | ## Diagnosing it Log the request — the request log prints the headers and cookies actually recorded on the specification, which is where a duplicated name is obvious in one line. If the header is being added by something you do not control, a filter can inspect and remove it before the request is sent. Reaching for the request log first is faster than reasoning about which specification contributed what. ## What to say in an interview Say that headers merge by default, that `Content-Type` and `Accept` are the two exceptions `HeaderConfig` ships, and that `overwriteHeadersWithName(...)` moves a name into the overwrite set. Then add the two details that show you have used it in anger: the switch replaces the default set rather than extending it, and cookies have no such control at all — they always accumulate into one `Cookie` header.