URL encoding is simple in principle and endlessly fumbled in practice. These six mistakes account for most of the broken links, failed API calls, and mangled characters we see, each with its symptom, its cause, and its fix.
1. Double encoding
Symptom: users see %2520 or literal %20 in rendered text, and searches for "caf%C3%A9" return nothing.
Cause: a value that was already percent-encoded went through an encoder again. The % in %20 gets encoded as %25, producing %2520. It usually happens when two layers of a system both feel responsible: a frontend encodes, then a backend or proxy encodes again.
Fix: decide which layer owns encoding and make it the only one. To repair existing data, decode repeatedly until the string stops changing, then encode once.
2. Encoding the whole URL as if it were a value
Symptom: a URL turns into https%3A%2F%2Fexample.com%2Fpath and nothing can open it.
Cause: running a complete URL through a component encoder such as JavaScript's encodeURIComponent, which faithfully encodes the colon and slashes that were structure, not data.
Fix: encode the parts, then assemble. Component encoders are for values you insert into a URL; they are the wrong tool for the URL itself. The only time a fully-encoded URL is correct is when that URL travels as a value inside another URL, such as a redirect parameter.
3. Assuming + always means a space
Symptom: a file named C++ notes.txt arrives as C notes.txt, or spaces survive as literal plus signs.
Cause: the plus sign means a space only in form-encoded data, the format of HTML form submissions and most query strings. In a path segment a plus is just a plus. Code that blindly replaces every + with a space corrupts legitimate plus signs; code that never does leaves form data full of them.
Fix: decode plus-as-space only in query strings and form bodies, never in paths. When encoding, %20 is always safe for a space.
4. Forgetting to encode a nested URL
Symptom: an OAuth flow or "return to" redirect loses its parameters; only the first one survives.
Cause: a URL placed inside another URL without encoding. The inner URL's ? and & are read as part of the outer one:
/login?next=/checkout?step=2&coupon=SAVE10
^ the outer URL claims coupon=SAVE10 for itselfFix: fully encode the inner URL before inserting it, so it becomes %2Fcheckout%3Fstep%3D2%26coupon%3DSAVE10. A query string parser makes it obvious which parameters belong to which URL.
5. Decoding with the wrong character set
Symptom: é becomes é, ü becomes ü, and curly quotes turn into three characters of noise.
Cause: the bytes were produced as UTF-8 but interpreted as ISO-8859-1 or Windows-1252, or the reverse. One character set turned into another mid-journey, usually at a legacy system boundary.
Fix: agree on UTF-8 end to end. When debugging old data, try decoding with each legacy charset until the text reads correctly; the mismatch tells you which system produced the bytes.
6. Trusting what the address bar shows you
Symptom: a URL looks clean in the browser, but the copied string is full of percent-escapes, so string comparisons and spreadsheets disagree.
Cause: browsers display a decoded, prettified URL while sending the encoded form on the wire. What you see is not what the server receives.
Fix: compare URLs in their encoded form, or decode both sides before comparing. When in doubt, paste the string into a decoder and look at what it really contains.