You POST a query string to your server, and in the server debug log you see q=hello%20world%26foo%3Dbar. Your first reaction is probably “did the server middleware get misconfigured? is something wrong with the parser?” The answer is, embarrassingly, simpler than that: this is RFC 3986 URL encoding (also called percent encoding) automatically replacing characters before the request even leaves the browser, and the server has nothing to do with it.

Percent encoding is, at its core, this: take any character that is unsafe or ambiguous inside a URL, and replace it with the form percent + two hex bytes. So a space becomes %20, an & becomes %26, an = becomes %3D. This way, URLs that travel across systems, protocols, and character sets don’t break because different systems interpret the same byte differently.

But RFC 3986 only defines what encoding “does”. It does NOT define who encodes, when, or how many times. Those three decisions are made independently by browsers, server frameworks, and client libraries, and the 8 common bugs all spring from that gap.

This post walks through the 8 most common URL encoding foot-guns, each one in a “symptom → why → fix” three-beat structure, and ends with a recommended browser-local tool, Piick URL Encoder / Decoder, which ships 3 modes (each returning the correct output for its domain), auto-detects double encoding, and surfaces warning chips so you can sanity-check your round-trip in under a minute.

30-Second Overview

  • URL encoding (percent encoding) is the RFC 3986 standard for replacing unsafe or ambiguous characters inside a URL with the form %XX (where XX is the byte’s hex value)
  • The JavaScript toolkit has three pieces: encodeURIComponent (component level, the safe default), encodeURI (whole URL but preserves /?&=# URL syntax characters — dangerous), and URLSearchParams (query strings only)
  • The 8 common foot-guns: double encoding, plus vs %20, un-encoded reserved characters, semicolons inside path segments (legal but ambiguous), Unicode not pre-encoded, OAuth state round-tripped through multiple hops, application/x-www-form-urlencoded mixed with application/json Content-Type, server-side default decode behavior varies by language
  • The fix direction is always the same: encode exactly once with encodeURIComponent(value), encode exactly once across the whole chain, and never re-encode something the previous hop already encoded
  • Use Piick URL Encoder / Decoder to encode or decode online, get the correct output for each of the 3 modes, and keep your data local. Sensitive callback URLs and API tokens never leave the browser

The 8 Common Foot-Guns

Foot-Gun 1: Double Encoding (The %2520 Is Not a Decode Failure)

Symptom: You get a string like %2520, run decodeURIComponent once and get %20, run it a second time and get the real (space). Your first thought is “where did I decode one extra time?”

Why it happens: A space encodes to %20 (four characters: percent, two, zero). Those four characters then get treated as four ordinary characters %, 2, 0 and “encoded again” by some framework or by you, producing %2520. Every hop that encodes adds another layer; if even one hop redundantly encodes a value that’s already been encoded, you get double encoding.

Common sources: server framework treating the whole URL string as a plain string and encoding again; or frontend URLSearchParams auto-encode layered on top of hand-written encodeURIComponent; or OAuth redirects where each redirect re-encodes. All three are the same bug at different scales.

Fix: Encode exactly once across the whole chain. Rule of thumb: the client (browser) does the encoding, the server does the decoding — and never the reverse. Paste your URL into Piick’s Full URL mode and it auto-detects double encoding and surfaces a warning chip, no counting %25 by eye needed.

Real-world scenario: an OAuth2 callback arrives with state=abc%2525xyz, the server decodes once and gets abc%25xyz, the business layer compares against the original and the values don’t match, the flow terminates with state mismatch.

Foot-Gun 2: Plus vs %20 (The Historic Form-Encoding Fork)

Symptom: A POST form body has q=hello+world and the server says “I read q as hello world, why is there a +?” Or the inverse: a URL path is path=/hello world and the server reads path as /hello world (space not encoded).

Why it happens: HTML form submission, when the form method is GET or the enctype is application/x-www-form-urlencoded, encodes spaces in form fields as + (NOT %20). This is a legacy convention from HTML 4 that applies only to form bodies and to the query strings of GET form submits. In URL paths and URL components, spaces always encode as %20. URLSearchParams is yet a third semantic (it treats + as a literal character, not a space). JS has three rules, and mixing them is the easiest way to ship a bug.

Fix:

  • URL paths and query parameter values use Piick Component mode — always %20
  • Form bodies and GET form submits use Piick Query mode — automatic + ↔ %20
  • Do not mix the three rule sets, even within the same app

Real-world scenario: You write fetch('/api?q=' + userInput) where userInput is hello world. The final URL is /api?q=hello world (space not encoded). The server-side router hits a space, throws URIError: URI malformed, the whole request dies.

Foot-Gun 3: Un-Encoded Reserved Characters, Server Splits Fields Wrong

Symptom: You build ?q=foo&bar=baz thinking you’ll get one parameter q=foo&bar=baz. The server actually receives two parameters, q=foo and bar=baz, and the second overwrites the first.

Why it happens: The URL parser sees & as the delimiter between parameters no matter what. So q=foo&bar=baz is two independent parameters. To treat & as a literal character inside the value, you must encode it with encodeURIComponent, which gives you %26.

Fix: Always process values with encodeURIComponent(value). Don’t do raw string concatenation, don’t use encodeURI (which preserves &), don’t skip encoding.

Real-world scenario: A GraphQL client concatenates a query into the URL — the query contains a GraphQL query with curly braces and parameters. Without encoding, the URL truncates at abc, the backend GraphQL parser throws a syntax error. 99% of these bugs are this one.

Foot-Gun 4: Semicolons and Slashes in Path Segments, Cross-Language Ambiguity

Symptom: A REST URL path design /users/john;doe. The backend’s Java Spring treats ;doe as a matrix parameter. Node.js Express treats the whole thing as one plain segment. Python Flask does something else. Same URL, three languages, three different results.

Why it happens: RFC 3986 lists ; under sub-delims, legal inside paths, but the semantics are ambiguous — RFC defines it as OPTIONAL matrix parameter semantics. / is the segment delimiter, but once it’s encoded (becoming %2F) different frameworks follow different conventions. Multiple behaviors, no consensus.

Fix: Use encodeURIComponent on each value inside each path segment (don’t encode the whole segment, only the values). If you must use matrix parameters, lock onto one framework and document it; don’t jump across languages.

Real-world scenario: Twitter’s early API paths contained semicolons (/statuses/show/:id.json;count=10). Python clients and the official Java SDK parsed those paths differently, and cross-language engineers had a daily debugging chore.

Foot-Gun 5: Unicode Not Pre-Encoded, Server UTF-8 / GBK Mangles

Symptom: A URL contains Chinese like “用户搜索”. The frontend sends the request directly. The server’s Nginx plus the backend return “query is garbled” or URIError: URI malformed.

Why it happens: encodeURIComponent("用户") outputs %E7%94%A8%E6%88%B7 (UTF-8 byte sequence). Directly concatenating non-ASCII characters into a URL is a violation of RFC — RFC defines an ASCII subset plus a percent-escape extension but does not specify how non-ASCII characters are transmitted. Even when Nginx is configured with charset utf-8, it handles URLs at the byte level and won’t guess character sets for you.

Fix:

  • Frontend: always encodeURIComponent(value) before concatenating. It naturally produces UTF-8 byte sequences.
  • Server side: do NOT try to “auto-detect character set”. Mandate that clients encode first.
  • While testing: open DevTools, look at the Network tab. If the request line is already %E7%94..., you’re good.

Real-world scenario: An overseas user searches “手机” on a Chinese e-commerce site. The frontend doesn’t encode, the server tries GBK decode and gets garbage, the search results don’t match the search query, conversion rate drops by half.

Foot-Gun 6: OAuth state Round-Tripped Through Multiple Hops, CSRF Defense Broken

Symptom: OAuth 2.0 callback arrives with state. Locally you encode and pass to the server. The server encodes again or implicitly encodes once. By the time the redirect reaches the endpoint, state doesn’t match the original value and the flow terminates.

Why it happens: OAuth’s state parameter is designed to be the round-trip identity of the originating request (CSRF defense). It has to travel local generate → encode → URL → cross network → server → decode → compare. Different OAuth libraries handle encode/decode defaults differently (Auth0 encodes by default, NextAuth doesn’t, Spring Security does something else), and cross-language cross-library collaborations go wrong.

Fix:

  • Once you commit to one OAuth library, use whatever encoding convention it recommends. Do NOT layer on manual encodeURIComponent.
  • Self-test: local encode → URL build → server decode → compare → must match
  • Use Piick URL Encoder / Decoder’s Query mode to compare raw and decoded on both ends

Real-world scenario: When integrating Notion or Google OAuth, default state mismatch bugs surface 3-5 times within a week. The common cause is that the developer adds their own encodeURIComponent on top of what the library already does.

Foot-Gun 7: application/x-www-form-urlencoded Mixed with JSON Content-Type

Symptom: You say “my POST body is JSON” but fetch adds Content-Type: application/x-www-form-urlencoded (or vice versa, the body is urlencoded format but Content-Type says JSON), and the server rejects or parses wrong.

Why it happens: The application/x-www-form-urlencoded Content-Type forces the body to go through the urlencoded parser, which treats every opening brace, closing brace, colon, and quote character in the body as an illegal character or a literal character. Conversely, the application/json parser expects the body to be valid JSON, and seeing urlencoded format throws SyntaxError.

Fix: Content-Type must match the actual body format. JSON uses application/json and the body is real JSON. Forms use application/x-www-form-urlencoded and the body is key=value&key2=value2.

Real-world scenario: Classic webhook debugging trap — Stripe sends a JSON webhook body, you copy the curl command and change Content-Type to urlencoded, the server parses the JSON string as literal parameters, every field comes back null.

Foot-Gun 8: Server-Side Default Decode Behavior Is Inconsistent Across Languages

Symptom: Your code decodeURIComponent(req.url) blows up on Node.js Express with URIError: URI malformed. You think the server has a bug, but the server already decoded before you got there.

Why it happens:

  • Node.js / Nginx / Apache / Go net/http / Spring / various server frameworks make different decisions about whether to pre-decode URLs
  • The usual convention: the path has been decoded once, the query has been decoded once (implicit)
  • Express does NOT decode by default. So when you write decodeURIComponent, req.url has already been decoded once and you get URIError.
  • But req.originalUrl shows raw, you can’t directly compare against it.

Fix:

  • Read the official docs, figure out the framework’s default decode behavior
  • Use Piick’s Component mode: one encode, one decode, no double in between
  • When the stack is layered (Express + Nginx + URL rewriter), check access.log and debug.log for the position of %20 — that pinpoints which layer introduced an extra encoding

Real-world scenario: An e-commerce app with three layers (Nginx + Express + ORM) gets bug reports “request parameters occasionally parse wrong”. The root cause is that the ORM framework decodes once internally, Nginx decodes once, Express decodes again — three decodes total, data is mangled.

Tool Selection Decisions

Three primary paths for URL encoding/decoding, each fits a different scenario:

Browser-side online tool (this blog / this tool)

Strengths: zero install, zero upload, friendly to sensitive callback URLs and API tokens. Three modes (Component / Query / Full URL) auto-determine the right encoding rules, auto-detect double encoding surfaces warning chips. Fits one-off debug, production incident triage, OAuth state troubleshooting. Piick URL Encoder / Decoder is this path — try it.

Node.js / browser-native functions (in your code)

  • encodeURIComponent(str) + decodeURIComponent(str) — component level, the daily default
  • encodeURI(str) + decodeURI(str) — whole URL, preserves /?&=# URL syntax characters. Unless you know exactly what you’re doing, don’t use this.
  • new URL(str) — parse a whole URL, mutate parts, then .toString()
  • URLSearchParams — query strings only. Does NOT treat raw + as space (the inverse of form encoding)

Fits build pipelines, unit tests, automation. The footer of Piick’s tool page has the complete RFC 3986 rules table for cross-referencing.

Server framework middleware (Express / Spring / Rails built-in)

The framework handles routine round-tripping so you don’t have to. Downside: edge cases (query containing ;, spaces, Unicode) the framework can’t help with; you still need a manual decodeURIComponent fallback. Fits CRUD form web apps, not recommended for high-security or high-complexity scenarios.

Cross-tool workflow recommendation: debug with a browser tool → write code with encodeURIComponent → run round-trip unit tests in CI → before webhook signing, run the canonical URL through Piick’s Full URL mode, then chain into the webhook signature validator to verify signatures match.

5 Real-World Scenarios

Scenario 1: OAuth2 state Callback Mismatch

Anti-pattern: encode locally, then the server encodes again automatically, round-trip fails. Fix: lock onto the OAuth library’s encoding behavior, don’t layer on top of manual encoding. Verify the round-trip by comparing the local end’s decoded result against the server’s decoded result in Piick’s Query mode.

Scenario 2: Webhook URL With Query, Normalize Before Signing

Preparing a webhook signature (Stripe / GitHub / Slack and others) typically uses a canonical string: normalize the URL (strip host, sort query keys, URL encode, then body hash, finally HMAC with the secret). In this chain, URL encoding happens exactly once, in the canonical string step. Piick’s Full URL mode helps you see exactly what the encoded string looks like. After signing, verify with the webhook signature validator to confirm the signature matches.

Scenario 3: You See %20 in Logs But It’s a Configuration Issue

When Nginx access.log shows double-encoded strings like %2520 and %2526, the cause is usually one hop in the redirect chain redundantly encoding. Locate it with grep + reverse decode:

For example, grep all access log entries containing %25, then grep the specific [URL]‘s redirect chain (the first few entries) to see at which hop %2520 first appears — that’s the hop with the bug.

Which hop does %2520 first appear in? That’s the hop with the bug.

Scenario 4: Front-End Builds Search URL Without Encoding, Server Splits Fields Wrong

Anti-pattern: fetch builds a search URL using string template concatenation where userInput is foo & bar. The URL becomes /api/search?q=foo & bar, the space is un-encoded, & gets treated as a parameter separator. Fix: wrap with encodeURIComponent(userInput). This is the most common root cause of “why is my query parameter wrong” tickets.

Scenario 5: REST URL Path Contains Special Characters

Anti-pattern: GET /api/users/john doe (with a space). The backend returns 404. Fix: encodeURIComponent('john doe') gives john%20doe, the final URL is /api/users/john%20doe, the backend receives john doe.

  • Always encodeURIComponent(value) for values. Never encodeURI, never skip encoding.
  • Encode exactly once across the whole chain: the client (browser) does the encoding, the server does the decoding, never the reverse. For multi-hop scenarios like OAuth or Webhooks, if each hop re-encodes you get double encoding. The rule is: encode exactly once across the entire chain.
  • Round-trip test before production: paste your original value into Piick, look at the encoded output, paste that output into the test environment, decode and verify you get the same value. This sanity check takes 5 seconds.
  • Don’t mix the three rule sets: URL components use Component mode, query strings use Query mode, form bodies use urlencoded. Don’t use one set on the JS side and another on the Python side.
  • Sensitive callback URLs and API tokens never leave your browser: use Piick URL Encoder / Decoder online, 100% local data, nothing uploaded.

URL encoding is unavoidable infrastructure baked into the HTTP protocol, but RFC 3986 gives you the “what” — the “how” is decided by your stack. After enough debugging, you’ll know the traps by heart, but until then, bookmark Piick URL Encoder / Decoder, open it for a 1-minute sanity check whenever things look off, don’t waste time.