⚡ SmartDevTools

URL Encoding (Percent-Encoding) Rules and Common Bugs

By SmarTech Apps · Published 2026-11-18 · 7 min read

A URL can only carry a small set of ASCII characters. Everything else, and every character that would otherwise be mistaken for URL structure, has to be written as a percent sign followed by two hexadecimal digits. The rules are simple, but the places where people apply them wrongly are many, and the bugs they cause are quiet ones: a search term that loses its plus sign, a redirect that never arrives, a filename that turns into mojibake.

Reserved and unreserved characters

RFC 3986 splits ASCII into two useful groups. Unreserved characters never need encoding and mean the same thing encoded or not: letters A-Z a-z, digits, and the four marks - . _ ~. Reserved characters are the delimiters that give a URL its shape: : / ? # [ ] @ and the sub-delimiters ! $ & ' ( ) * + , ; =.

A reserved character is only "safe" when it is doing its structural job. A / separates path segments, a ? starts the query, & separates parameters, = separates a name from a value and # starts the fragment. If you want one of those characters to appear as data, for instance an ampersand inside a company name, you must encode it, otherwise the parser will read it as structure. Everything outside both groups (spaces, quotes, angle brackets, non-ASCII letters) must always be encoded.

How the encoding itself works

Percent-encoding operates on bytes, not characters. The text is first converted to UTF-8, and each byte that needs encoding becomes % plus two hex digits. A space is byte 0x20, so it becomes %20. The letter é is two bytes in UTF-8, so it becomes %C3%A9. An emoji such as 😀 is four bytes: %F0%9F%98%80. These values come straight from running the encoders in JavaScript and Python, and you can reproduce them in the URL Encoder.

encodeURIComponent('é')   // "%C3%A9"
encodeURIComponent('😀')  // "%F0%9F%98%80"
urllib.parse.quote('é')   # '%C3%A9' (Python)

Hex digits are case-insensitive, so %c3%a9 and %C3%A9 are equal, though uppercase is the conventional form. A decoder must reassemble the bytes and interpret them as UTF-8; decoding a lone %A9 gives invalid UTF-8, which is a common sign that somebody encoded in Latin-1 on the way in.

encodeURI versus encodeURIComponent

JavaScript ships two functions and choosing the wrong one is the most common mistake of all. encodeURIComponent is for a single piece: a query value, a path segment. It escapes every reserved character, leaving only letters, digits and - _ . ! ~ * ' ( ). encodeURI is for a whole URL that is already structured: it leaves : / ? # & = and friends alone and only escapes characters that are illegal anywhere.

encodeURI('https://a.com/a b?q=x&y=é#f')
// "https://a.com/a%20b?q=x&y=%C3%A9#f"

encodeURIComponent('x&y=1')
// "x%26y%3D1"

Two mistakes follow. Running encodeURIComponent on a whole URL produces https%3A%2F%2F..., which is no longer a URL at all. Running encodeURI on a parameter value leaves &, = and # intact, so a value like a&admin=true injects a second parameter. The URL Encoder offers both a component mode and a full-URL mode for exactly this reason; pick the one that matches what you are pasting.

Space: %20 or +?

Both appear in the wild because there are two specifications. In a generic URI, a space is %20 and a plus sign is simply a plus sign. In application/x-www-form-urlencoded, the format used by HTML forms and many query strings, a space is written as +, and a literal plus must be %2B. Servers that parse query strings as form data turn + into a space; a path is never parsed that way, so /my+file really means a file with a plus in its name.

The practical rule: use %20 unless you know the receiver expects form encoding, and always encode a literal plus as %2B. A phone number like +44 20 7946 0000 sent unencoded in a query arrives with a leading space instead of the plus, a classic silent bug. When decoding, the URL Encoder has a form-encoding toggle so you can read + as a space only when that is correct.

InputGeneric URIForm encoding
space%20+
plus sign+ or %2B%2B
ampersand%26%26
é%C3%A9%C3%A9

Encode the parts, not the whole

The cleanest rule is: encode each value individually, then assemble. String-concatenate an already-encoded URL with raw user input and you have two layers of meaning mixed together. The safe way is to let a library build the query:

const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'café & crème 50% off');
url.toString();
// https://api.example.com/search?q=caf%C3%A9+%26+cr%C3%A8me+50%25+off

URLSearchParams uses form encoding, which is why spaces came out as +. That is valid for query strings, and every mainstream server decodes it. If you hand-build URLs, encode each value with encodeURIComponent and join with & yourself. Python has urllib.parse.urlencode and quote for the same purpose; note that quote leaves / unescaped by default, so pass safe='' when encoding a value that may contain slashes.

Paths, slashes and fragments

A path parameter that may contain a slash is a trap. A file called reports/2026 placed in /files/{name} must become /files/reports%2F2026 to remain one segment. Be aware that some web servers and proxies reject or normalise %2F in paths, so for arbitrary strings an ID or a query parameter is a safer design than embedding the text in the path.

The fragment (everything after #) is never sent to the server; the browser keeps it. So encoding matters for client-side code reading location.hash, but a server will never see it. Likewise, a # that you forgot to encode in a query value silently truncates the request: ?color=#ff0000 sends color= and nothing else.

Double encoding and its symptoms

Double encoding happens when already-encoded text is encoded again: %20 becomes %2520, because the percent sign itself is encoded as %25. You will see literal %20 showing up in file names or on screen. It usually means two layers (a framework and your own code, or a redirect and a link builder) each did their job. The fix is to encode exactly once, at the boundary where raw data enters the URL, and never encode something you received from a URL without decoding it first.

The opposite fault, decoding twice, is a security matter. If a filter checks the string after one decode and the application decodes again, %252e%252e%252f becomes ../ at the second stage and walks past a path-traversal check. Decode once, then validate the result.

Security notes: redirects and injection

Encoding is not a security boundary by itself, but forgetting it opens doors. A ?next= parameter holding a full URL should be encoded, and then, importantly, validated against an allow-list on the server; otherwise it is an open redirect that attackers use for phishing. Unencoded & and # in user input allow parameter injection, as shown earlier. Output context matters too: a URL placed inside HTML needs HTML escaping on top (& becomes & in an attribute; see the HTML Entity Encoder), and percent-encoding is a different thing from Base64, which is covered in Base64 is not encryption.

When a request misbehaves, the quickest check is to paste the suspicious URL into the URL Encoder in decode mode, or replay it with the cURL Builder and compare. For what a server does with a malformed request, see HTTP status codes explained: a bad encoding most often earns a 400.

Try the tools

Keep reading