URL Encoding — What It Is, When It Breaks, and How to Fix It

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. The server gets garbage, returns an error, and you're left staring at a URL that looks perfectly reasonable.

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.

// JavaScript
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.

// JavaScript
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 is simple: 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 — the path, query string, or fragment.

+ 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 bug this causes: a server receives q=hello+world from a form submission and decodes it correctly as "hello world". But then you construct a URL manually using encodeURIComponent(), which produces q=hello%20world. Both work. Problems appear when you mix decoding functions — if a server decodes %20 as a literal %20 string rather than a space, or decodes + in a path as a space, things break silently.

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 or library 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, then re-encode cleanly:

// Safe approach: decode then re-encode
function safeEncode(str) {
  // Decode first in case it's already encoded, then encode cleanly
  try {
    return encodeURIComponent(decodeURIComponent(str));
  } catch (e) {
    // If decoding fails, it wasn't encoded — encode as-is
    return encodeURIComponent(str);
  }
}

Characters that have special meaning

These characters are "reserved" in URLs — they have structural meaning and 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

These are "unreserved" — they never need encoding and should not be encoded:

A–Z   a–z   0–9   -   _   .   ~

Note that encodeURIComponent() does not encode: A–Z a–z 0–9 - _ . ! ~ * ' ( ). If you need those encoded too (for example, in an OAuth signature), you'll need to add them manually after encoding.

Decoding URL-encoded strings

// JavaScript
decodeURIComponent("hello%20world")     // → "hello world"
decodeURIComponent("caf%C3%A9")         // → "café"
decodeURIComponent("price%3D5%26qty%3D2") // → "price=5&qty=2"

// Decode a full URL (leaves structure intact)
decodeURI("https://example.com/search?q=hello%20world")
// → "https://example.com/search?q=hello world"

// Handle malformed input safely
function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    return str; // Return original if decoding fails
  }
}

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"
quote("https://x.com/a b", safe=":/?#[]@!$&'()*+,;=")
# safe= controls which chars are NOT encoded

// PHP
urlencode("hello world")      // → "hello+world"  (form encoding)
rawurlencode("hello world")   // → "hello%20world" (RFC 3986)
urldecode("hello+world")      // → "hello world"
rawurldecode("hello%20world") // → "hello world"

// Note: PHP's urlencode() uses + for spaces (form encoding)
// Use rawurlencode() for URL paths and components

// Go
import "net/url"
url.QueryEscape("hello world")    // → "hello+world"
url.PathEscape("hello world")     // → "hello%20world"
url.QueryUnescape("hello+world")  // → "hello world"

Encoding a redirect URL as a parameter

One of the trickiest real-world cases: a redirect URL that is itself a query parameter.

// You want to build:
// /login?next=https://example.com/dashboard?tab=settings&view=list

// Wrong — the inner ? and & break the outer URL structure
const next = "https://example.com/dashboard?tab=settings&view=list";
const url = `/login?next=${next}`;
// → /login?next=https://example.com/dashboard?tab=settings&view=list
//   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

On the receiving end, the server decodes the next parameter and gets back the original URL intact.

Query string construction the right way

Instead of manually encoding and concatenating query parameters — which is error-prone — use the platform's built-in tools:

// JavaScript — 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"
// Note: URLSearchParams uses + for spaces (form encoding)

// 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
const params = new URL(window.location.href).searchParams;
const query = params.get("q"); // Already decoded for you

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() or decode with the correct function on the server.

%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. In older server environments, check the encoding configuration.

A parameter value is empty on the server — the value contains characters that terminate the parameter without encoding, or the value itself is being mistaken for a parameter name. Encode the value.

URL works in the browser but fails in curl or a fetch call — browsers are lenient and will often fix malformed URLs automatically. HTTP clients won't. Always encode explicitly when constructing URLs in code.

URL encoding — what it is, when it breaks, and how to fix it