A Query Value Needs a Boundary, Not Another Escape

When a URL behaves oddly, the reflex is to add another layer of encoding to the suspect value. The reflex usually makes it worse. A query value does not need more escaping; it needs an agreed boundary that says where the value starts and ends, and exactly one encoding pass applied inside that boundary.

Watch the same value cross two boundaries

Value: orders/2026?status=open

  • As a path segment: orders%2F2026%3Fstatus%3Dopen — both reserved characters escaped
  • As a query value: value=orders%2F2026%3Fstatus%3Dopen — same escapes, different container
  • Encoded twice anywhere: %252F appears, and no single decode restores the original

Parse the boundary →

The workbench separates the two jobs

The URL Workbench parses the structural fields of the URL — scheme, host, path, query — and treats each query value as its own document with its own decoding. The two views stay apart on purpose. Mixing them is what produces the classic bugs: a value decoded with + read as a space in a context where it meant a literal plus, or a slash decoded in a path where the router still expected a separator.

What to record in the contract

One sentence is enough: this parameter is percent-encoded UTF-8, plus signs are data, and it is encoded exactly once by the client wrapper. Every consumer downstream of that sentence can decode confidently, and every producer upstream knows the pass it must not repeat.

Diagnosis stays local in the browser: paste the URL, compare the raw and decoded views side by side, and the boundary that was being argued about becomes visible as text.

Why the second pass is so tempting

The extra escape usually enters through a helpful wrapper: a logging library that “fixes” URLs before writing them, a retry layer that rebuilds the request from a string, a test helper that pre-encodes fixtures to be safe. Each layer acts alone and looks harmless. The failure only appears when a value with reserved characters meets two of them, and by then the layers are spread across services.

The audit that fixes it permanently is short: list every function that touches the URL between creation and transmission, and leave exactly one responsible for encoding. Everything else either receives raw strings or emits already-encoded ones, and the type signature should say which.