URL encoding bugs are some of the most frustrating to debug because they're invisible. A string looks fine in your code, but by the time it arrives at the server it's been mangled — spaces became + signs, the & that was part of your data got interpreted as a query string separator, or the whole parameter silently disappeared.
This guide covers how URL encoding works, where it goes wrong, and the exact functions to use in JavaScript and other languages to handle it correctly every time.
What URL encoding actually is
URLs can only contain a specific set of characters safely: letters (A–Z, a–z), digits (0–9), and a handful of special characters (-, _, ., ~). Everything else — spaces, ampersands, equals signs, slashes, non-ASCII characters — needs to be encoded before it can be included in a URL without breaking its structure.
The encoding scheme is called percent-encoding. Each unsafe character is replaced by a percent sign followed by its two-digit hexadecimal ASCII code. A space becomes %20, an ampersand becomes %26, an equals sign becomes %3D, a forward slash becomes %2F.
Hello World → Hello%20World
user@example → user%40example
price=5&qty=2 → price%3D5%26qty%3D2
café → caf%C3%A9
Non-ASCII characters like accented letters and emoji are first encoded to UTF-8 bytes, then each byte is percent-encoded. That's why café becomes caf%C3%A9 — the é character is two bytes in UTF-8 (0xC3, 0xA9), each percent-encoded.
The two contexts that confuse everyone
URL encoding isn't one thing — it's two different operations applied in two different places, and mixing them up is the root cause of most encoding bugs.
Encoding a full URL
When you have a complete URL and want to make it safe to use as a link or pass to a browser, you want to encode only the characters that are illegal in URLs entirely — but leave the structural characters (:, /, ?, #, &, =) alone, because those are part of the URL's structure.
encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
// Note: & and = are NOT encoded — they're structural
Encoding a query parameter value
When you're inserting a value into a URL — a search term, a redirect URL, a user-submitted string — you need to encode everything that isn't a plain alphanumeric character, including the structural characters. If your value contains an & and you don't encode it, the browser will interpret it as a parameter separator and split your value in two.
encodeURIComponent("hello world & more")
// → "hello%20world%20%26%20more"
// Note: & IS encoded as %26 — it's data, not structure
// Building a URL with a parameter
const query = "price < 100 & in stock";
const url = `https://example.com/search?q=${encodeURIComponent(query)}`;
// → "https://example.com/search?q=price%20%3C%20100%20%26%20in%20stock"
The rule: use encodeURI() on complete URLs. Use encodeURIComponent() on individual values being inserted into URLs. Use encodeURIComponent() far more often than encodeURI().
The space problem: %20 vs +
Spaces are the single most common source of URL encoding confusion because there are two valid encodings for them, used in different contexts:
%20 is the standard percent-encoding for a space and works correctly in any part of a URL.
+ represents a space only in the query string of application/x-www-form-urlencoded content — the format HTML forms use when submitted. In a URL path, + is a literal plus sign, not a space.
// These are equivalent in a query string:
https://example.com/search?q=hello+world
https://example.com/search?q=hello%20world
// But in a path, + is literal:
https://example.com/files/hello+world.txt // file named "hello+world.txt"
https://example.com/files/hello%20world.txt // file named "hello world.txt"
The safe rule: always use %20 for spaces unless you're specifically working with HTML form submissions. Never rely on + outside of form data.
Double-encoding — the silent killer
Double-encoding happens when you encode something that's already encoded. The result looks almost right but is subtly broken:
// Original string
"hello world"
// Encoded once (correct)
"hello%20world"
// Encoded twice (broken — the % itself gets encoded)
"hello%2520world"
// ↑ %25 is the encoding for %, so %20 became %2520
When the server receives hello%2520world and decodes it once, it gets hello%20world — a string containing a literal percent sign, two, zero. Not the space you intended.
Double-encoding happens most often when:
- You encode a value, then pass it through a function that encodes again
- You build a URL from already-encoded parts and then encode the whole URL
- A framework encodes parameters automatically and you've also encoded them manually
- You're constructing a redirect URL where the target URL is itself a query parameter
The fix is to decode first if you're unsure whether something is already encoded:
function safeEncode(str) {
try {
return encodeURIComponent(decodeURIComponent(str));
} catch (e) {
return encodeURIComponent(str);
}
}
Characters that have special meaning
Reserved — must be encoded when used as data:
: %3A / %2F ? %3F # %23
[ %5B ] %5D @ %40 ! %21
$ %24 & %26 ' %27 ( %28
) %29 * %2A + %2B , %2C
; %3B = %3D
Unreserved — never need encoding:
A–Z a–z 0–9 - _ . ~
Note that encodeURIComponent() does not encode: A–Z a–z 0–9 - _ . ! ~ * ' ( ). If you need those encoded too (e.g. in an OAuth signature), you'll need to add them manually after encoding.
Decoding URL-encoded strings
decodeURIComponent("hello%20world") // → "hello world"
decodeURIComponent("caf%C3%A9") // → "café"
decodeURIComponent("price%3D5%26qty%3D2") // → "price=5&qty=2"
// Handle malformed input safely
function safeDecode(str) {
try {
return decodeURIComponent(str);
} catch (e) {
return str;
}
}
URL encoding in other languages
# Python
from urllib.parse import quote, unquote, quote_plus, unquote_plus
quote("hello world") # → "hello%20world"
quote_plus("hello world") # → "hello+world" (form encoding)
unquote("hello%20world") # → "hello world"
// PHP
urlencode("hello world") // → "hello+world" (form encoding)
rawurlencode("hello world") // → "hello%20world" (RFC 3986)
// Use rawurlencode() for URL paths and components
// Go
import "net/url"
url.QueryEscape("hello world") // → "hello+world"
url.PathEscape("hello world") // → "hello%20world"
Encoding a redirect URL as a parameter
One of the trickiest real-world cases — a redirect URL that is itself a query parameter:
// Wrong — the inner ? and & break the outer URL structure
const next = "https://example.com/dashboard?tab=settings&view=list";
const url = `/login?next=${next}`;
// The server sees next=https://example.com/dashboard?tab=settings
// and &view=list as a separate parameter
// Correct — encode the entire redirect URL as a value
const url = `/login?next=${encodeURIComponent(next)}`;
// → /login?next=https%3A%2F%2Fexample.com%2Fdashboard%3Ftab%3Dsettings%26view%3Dlist
Query string construction the right way
Instead of manually encoding and concatenating — which is error-prone — use built-in tools:
// URLSearchParams handles encoding automatically
const params = new URLSearchParams({
q: "hello world & more",
lang: "en",
page: 1
});
console.log(params.toString());
// → "q=hello+world+%26+more&lang=en&page=1"
// Append to a URL
const url = new URL("https://example.com/search");
url.searchParams.set("q", "hello world & more");
url.searchParams.set("lang", "en");
console.log(url.toString());
// → "https://example.com/search?q=hello+world+%26+more&lang=en"
// Read parameters safely — already decoded for you
const params = new URL(window.location.href).searchParams;
const query = params.get("q");
Common encoding bugs and their fixes
Parameter value contains & and gets split — you're not encoding the value before inserting it. Use encodeURIComponent() on the value.
Spaces arrive at the server as literal + — you're using form encoding (+) in a context that expects percent-encoding. Switch to encodeURIComponent().
%25 appears where %20 should be — double-encoding. Find where you're encoding already-encoded data and remove the redundant step.
Non-ASCII characters arrive garbled — the string isn't being encoded to UTF-8 before percent-encoding. In JavaScript, encodeURIComponent() always uses UTF-8.
A parameter value is empty on the server — the value contains characters that terminate the parameter without encoding. Encode the value.
URL works in the browser but fails in fetch or curl — browsers are lenient and will often fix malformed URLs automatically. HTTP clients won't. Always encode explicitly when constructing URLs in code.
If you need to quickly encode or decode a URL or string, DevCrate's URL Encoder/Decoder runs entirely in your browser — nothing you paste is sent anywhere.
Top comments (0)