URL Encoding Bugs: Spaces, Symbols, and Percent-Encoding
A practical checklist for debugging URL encoding problems across query strings, reserved characters, plus signs, double encoding, and redirects.
Quick answer
Identify the URL component before encoding it. Encode parameter values rather than the assembled URL, and decode only at the expected boundary. Test reserved characters, plus signs, Unicode, and already-encoded values to catch double encoding.

URL encoding bugs are easy to create and hard to spot. A request can look normal in a browser, fail in an API client, and break again after being copied into a redirect URL. The tricky part is that URLs use some characters as data and some characters as structure.
Encoding is the boundary between those two meanings. If you encode too little, data becomes structure. If you encode too much, structure becomes data.
Name the URL Part First
Before changing any encoding code, identify which part of the URL you are handling.
- Scheme
- Host
- Path segment
- Query key
- Query value
- Fragment
- Full URL passed as a parameter
Each part has different rules. Encoding a full URL the same way you encode one query value is a common source of broken redirects and callback links.
The URL Encoding Checklist
1. Encode Values, Not the Whole Query String
When building query strings, encode each key and each value separately. Do not concatenate raw strings and then encode the entire result.
const params = new URLSearchParams()
params.set("q", "a value with spaces")
params.set("redirect", "https://example.com/a?x=1")Let the URL API handle separators. That keeps ?, &, and = as structure while encoding them correctly when they appear inside values.
2. Watch the Plus Sign
In some form-encoded contexts, + represents a space. In other URL contexts, a plus sign is just a plus sign.
This matters for search queries, email aliases, Base64-like values, and signed tokens. If a + changes to a space, the decoded value is no longer the same data.
When debugging, compare the raw URL, parsed query value, and decoded value. Do not rely only on what the browser address bar displays.
3. Detect Double Encoding
Double encoding happens when already-encoded data gets encoded again.
hello%20world
hello%2520worldThe second value contains %25, which is the encoded form of %. That usually means one layer encoded a value that another layer had already prepared.
Double encoding often appears in redirects, nested callback URLs, signed links, and framework helpers that encode automatically.
4. Keep Path Segments Separate
Path segments should be encoded segment by segment. A slash inside a value is not the same as a slash separating path segments.
If a user-provided value can contain /, encode it before placing it into a path. Otherwise, one value can accidentally become multiple route segments.
5. Do Not Decode Too Early
Decoding at the wrong layer can introduce bugs or security issues. A router, framework, proxy, or server may already decode part of the URL before your application sees it.
If you decode again, values can change unexpectedly. This is especially risky for redirect targets, file paths, and values that may contain encoded separators.
6. Test With Unfriendly Values
Do not test URL encoding with only simple words. Use values that exercise the boundary:
- Spaces
+&=?/%- Unicode characters
- Full URLs as values
If those values survive a round trip, the normal cases usually will.
Use a URL Encoder Before Shipping
Use the URL Encoder at /tools/url-encoder/ when you need to inspect how a value changes through encoding and decoding. Use the URL Query Parser at /tools/url-query-parser/ when you need to inspect parsed query keys and values.
URL encoding is not about making a string look strange. It is about preserving the difference between URL structure and user data.
Sources and further reading
These references explain the standards and APIs discussed in this guide. Check the documentation for the versions and services in your environment.
Related Posts

Fetch Timeouts: Cancel Slow Requests and Response Bodies
Use AbortSignal to bound fetch and body reads, preserve caller cancellation, and test timeout behavior with a working local HTTP server.

Cursor Pagination: Stop Repeating Rows in a Changing Feed
Build stable cursor pagination with a runnable JavaScript example, timestamp tie-breakers, PostgreSQL queries, and a practical API checklist.

Promise.all Is Not a Concurrency Limit: Bound API Fan-Out
Limit API fan-out with a tested JavaScript worker pool that preserves result order, records failures, and bounds active tasks.