URLSearchParams Duplicate Keys: Preserve Values Before Object Conversion

Locate the conversion that drops values#

URLSearchParams holds an ordered list of name/value pairs. The WHATWG URL Standard defines get() as the first matching value and getAll() as all matching values in list order. A missing name returns null from get() and an empty array from getAll().

Object.fromEntries() creates properties from successive entries. Repeated string keys write the same property again, so the last value survives. The original URLSearchParams instance still has every pair; the loss happens in the new object.

For tag=js&tag=node, choose the representation according to your field’s contract:

These outcomes follow from the APIs and are verified below. None of them establishes what a backend framework will do with the same raw query string. Define that separately rather than assuming browser and server parsers agree.

Reproduce the loss and the round-trip boundary#

Save this dependency-free fixture as query-params.mjs and run node query-params.mjs. It was executed during article preparation on macOS with Node.js 24.13.0 on October 8, 2026. Its assertions check the results rather than relying only on printed examples.

1
import assert from 'node:assert/strict';
2

3
function readOne(params, name) {
4
  const values = params.getAll(name);
5
  if (values.length > 1) throw new Error(`Duplicate ${name}`);
6
  return values.length === 0 ? null : values[0];
7
}
8

9
const query = 'tag=js&tag=node&page=1&page=2&empty=';
10
const params = new URLSearchParams(query);
11
const flat = Object.fromEntries(params);
12
const tags = params.getAll('tag');
13
assert.equal(params.get('tag'), 'js');
14
assert.equal(flat.tag, 'node');
15
assert.deepEqual(tags, ['js', 'node']);
16
console.log('get(tag):', params.get('tag'));
17
console.log('object.tag:', flat.tag);
18
console.log('getAll(tag):', JSON.stringify(tags));
19

20
assert.throws(() => readOne(params, 'page'), /Duplicate page/);
21
try {
22
  readOne(params, 'page');
23
} catch (error) {
24
  console.log('readOne(page):', error.message);
25
}
26
assert.equal(readOne(params, 'missing'), null);
27
assert.equal(readOne(params, 'empty'), '');
28
console.log('missing:', JSON.stringify(readOne(params, 'missing')));
29
console.log('empty:', JSON.stringify(readOne(params, 'empty')));
30

31
const replaced = new URLSearchParams(params);
32
replaced.set('tag', 'css');
33
assert.deepEqual(replaced.getAll('tag'), ['css']);
34
console.log('after set:', replaced.toString());
35

36
const kept = new URLSearchParams();
37
for (const tag of tags) kept.append('tag', tag);
38
assert.deepEqual(kept.getAll('tag'), tags);
39
console.log('append round trip:', kept.toString());
40

41
const collapsed = new URLSearchParams(flat);
42
assert.deepEqual(collapsed.getAll('tag'), ['node']);
43
console.log('object round trip:', collapsed.toString());
44

45
const arrayRecord = new URLSearchParams({ tag: tags });
46
assert.deepEqual(arrayRecord.getAll('tag'), ['js,node']);
47
console.log('array record:', arrayRecord.toString());
48
console.log('assertions: passed');

Expected output from that environment:

1
get(tag): js
2
object.tag: node
3
getAll(tag): ["js","node"]
4
readOne(page): Duplicate page
5
missing: null
6
empty: ""
7
after set: tag=css&page=1&page=2&empty=
8
append round trip: tag=js&tag=node
9
object round trip: tag=node&page=2&empty=
10
array record: tag=js%2Cnode
11
assertions: passed

The object round trip loses both the first tag and the first page value. The append round trip preserves both tags. Keeping an array inside a plain object is useful application state, but passing that array-valued object directly to the constructor does something different: it serializes the array as a single comma-separated value. The Node.js constructor documentation documents string coercion for object values, including arrays.

tag=js%2Cnode therefore represents one value, 'js,node', when read back through this API. It is not equivalent to tag=js&tag=node. A server might explicitly implement comma-separated lists, but that would be a separate endpoint contract.

Parse by field, then serialize deliberately#

For a search page with repeated tags and one optional page parameter, keep the query instance until you have validated each field:

1
// Use readOne() from the fixture above.
2
const params = new URLSearchParams('tag=js&tag=node&page=2');
3
const filters = {
4
  tags: params.getAll('tag'),
5
  page: readOne(params, 'page'),
6
};
7

8
const outgoing = new URLSearchParams();
9
for (const tag of filters.tags) outgoing.append('tag', tag);
10
if (filters.page !== null) outgoing.set('page', filters.page);
11
console.log(outgoing.toString()); // tag=js&tag=node&page=2

This example’s duplicate policy is intentional: tags may repeat; page may not. readOne() rejects even identical repeated page values. It distinguishes an absent field from an explicitly empty field, but it does not validate page numbers, tag membership, maximum counts, or input length. Add those checks to match your application before using the parsed values.

set() replaces the first matching pair and removes other pairs with that name. That makes it suitable for replacing one scalar field, but it destroys a repeated list. To replace the entire tag selection, delete the old list first and append each new value:

1
const params = new URLSearchParams('tag=js&tag=node&page=2');
2
params.delete('tag');
3
for (const tag of ['css', 'html']) params.append('tag', tag);
4
console.log(params.toString()); // page=2&tag=css&tag=html

The unrelated page parameter remains. The replacement tags move to the end of the pair list; this example preserves their selection order, not the original query’s complete ordering. Avoid this rewrite when a separate system requires an exact original query representation.

Check the request boundary#

Use new URL(fullUrl).searchParams when the input is a complete URL. In a browser, new URLSearchParams(location.search) accepts the query portion. The fixture exercises standard query operations in Node, not framework routing, browser navigation, a live endpoint, or a proxy’s duplicate-parameter handling.

For an affected request, compare the raw query, Array.from(params.entries()), and the object produced after conversion. That identifies whether values disappeared during parsing, flattening, or outgoing serialization. If the request reaches the server but fails later, the separate fetch status and JSON parsing checks help distinguish HTTP failure from response parsing.

Make the cardinality rule explicit at the first parsing boundary: retain arrays for repeated fields, reject duplicates for single-value fields, and use append() when the outgoing query must preserve multiple values.

References:

• WHATWG URL Standard: URLSearchParams
• ECMAScript: Object.fromEntries
• MDN: URLSearchParams.getAll()
• MDN: URLSearchParams.set()
• Node.js: URLSearchParams object constructor