URL-Decoder

What is URL Decoding (Percent-Decoding)?

URL decoding — formally called percent-decoding — reverses the percent-encoding process defined in RFC 3986. It takes a string containing percent-encoded sequences like %20, %3A, or %E2%9C%93 and reconstructs the original characters they represent. This operation is essential when debugging HTTP requests, inspecting query parameters from server logs, analyzing redirect chains, or extracting human-readable text from encoded URLs pasted into chat or documentation. Unlike encoding (which always succeeds for any input), decoding can fail when the input contains malformed percent sequences, incomplete multi-byte characters, or invalid hexadecimal digits — making robust error handling a critical concern for any decoding tool.

How Percent-Decoding Works

The percent-decoding algorithm scans the input string character by character. When it encounters a percent sign (%) followed by exactly two hexadecimal digits (0–9, A–F, a–f), it converts that three-character sequence into the corresponding byte value. For example, %20 becomes byte 0x20 (space), %2F becomes 0x2F (forward slash), and %C3%A9 becomes the two-byte UTF-8 sequence for "é". Characters that are not preceded by a percent sign pass through unchanged, and the plus sign (+) is optionally interpreted as a space in the application/x-www-form-urlencoded format used by HTML forms — a legacy convention that predates RFC 3986.

Once all percent sequences are converted to raw bytes, the resulting byte sequence is interpreted as UTF-8 text. This two-stage process — percent-to-bytes then bytes-to-characters — is why multi-byte Unicode characters produce multiple percent-encoded triplets: the Japanese character "日" is encoded as %E6%97%A5 (three bytes in UTF-8), and decoding must reassemble all three before interpreting the character. Truncating the sequence at %E6%97 would produce a URIError because the byte sequence is not valid UTF-8.

Malformed Input and URIError Handling

Decoding is inherently more error-prone than encoding because malformed input can produce undefined results. The JavaScript decodeURIComponent() function throws a URIError when it encounters sequences that cannot be interpreted as valid UTF-8. Common failure scenarios include:

• Incomplete percent triplet: A percent sign followed by fewer than two hex digits (e.g., %2 or % at end of string) is syntactically invalid and produces a URIError.
• Invalid hex digits: Sequences like %GH or %ZZ contain characters outside the hexadecimal range and cannot be decoded.
• Broken UTF-8 sequences: Bytes like %C3 without their continuation byte produce invalid UTF-8 that the decoder cannot interpret as any character.
• Lone surrogate halves: Sequences encoding UTF-16 surrogates (U+D800 to U+DFFF) are invalid in UTF-8 and are rejected by compliant decoders.

This tool wraps decoding in proper error handling, catching URIError exceptions and reporting the exact position and nature of the malformed sequence. Rather than silently dropping undecodable bytes or replacing them with the Unicode replacement character (U+FFFD), it highlights the problematic segment so you can fix the source of the encoding error.

Detecting and Resolving Double-Encoding

Double-encoding is one of the most common bugs in web applications that handle URLs. It occurs when an already-encoded string is passed through an encoding function a second time, turning %20 into %2520 (the percent sign itself gets encoded). Symptoms of double-encoding include:

• URLs that display %2520 instead of spaces in browser address bars
• Query parameters containing %253D instead of = signs
• Redirect URLs that 404 because the path contains literal %2F sequences decoded once to / but the server expects a single decode
• API responses where JSON string values contain %22 instead of quote characters

To diagnose double-encoding, decode the string once and inspect the result. If the output still contains percent-encoded sequences (matches the pattern %[0-9A-Fa-f]{2}), the original was likely double-encoded. Decode again and compare. This tool makes this workflow easy by showing the decoded output immediately — if you see remaining percent sequences, paste the output back for a second decode pass. In production code, implement detection by checking if the decoded output still contains valid percent-encoded sequences and decode iteratively until stable.

decodeURIComponent vs decodeURI: Choosing the Right Function

JavaScript provides two built-in decoding functions with important differences. decodeURI() decodes a full URI but preserves characters that have special meaning in URI syntax: # $ & + , / : ; = ? @. It is designed for decoding complete URLs where you want the structure to remain intact. decodeURIComponent() decodes everything, including those reserved characters — it is designed for decoding individual URI components like a query parameter value or a path segment.

Using the wrong function leads to subtle bugs. If you pass a full URL to decodeURIComponent(), encoded slashes (%2F) in the path become literal slashes, potentially changing the URL's routing semantics. Conversely, if you use decodeURI() on a query parameter value that legitimately contains an encoded ampersand (%26), it decodes it to & — splitting what should be a single parameter into two. This tool applies decodeURIComponent() by default because the most common use case is decoding individual values extracted from URLs, but understanding when to use each function prevents data corruption in your application code.

Debugging Encoded URLs in Real-World Scenarios

URL decoding is a critical step in several debugging workflows that developers encounter daily:

• Server log analysis: Web server access logs record request URIs with percent-encoding intact. Decoding reveals the actual search queries, file names, and parameter values users submitted.
• Redirect chain inspection: OAuth flows and SSO systems pass callback URLs as encoded parameters within other URLs. Decoding each layer reveals the full redirect chain and helps identify where authentication failures originate.
• Deep link debugging: Mobile deep links and universal links encode complex parameters (JSON payloads, nested URLs) that must be decoded to verify correctness.
• SEO audit: Crawlers may report URLs with encoded characters differently than browsers display them. Decoding canonical URLs confirms whether duplicates are true duplicates or encoding variations.
• Webhook payload inspection: Form-encoded webhook bodies from payment processors, CRM systems, and notification services arrive as percent-encoded key-value pairs that need decoding to read.

This tool handles all these scenarios by accepting any percent-encoded input — whether it is a complete URL, a single query parameter value, or a form-encoded request body — and producing the decoded human-readable result with clear error reporting for any malformed segments.

Code Examples

Safe URL decoding with URIError handling in JavaScript

// Safe decode that catches malformed sequences
function safeDecode(encoded) {
  try {
    return { success: true, value: decodeURIComponent(encoded) };
  } catch (e) {
    if (e instanceof URIError) {
      return { success: false, error: 'Malformed percent-encoding: ' + e.message };
    }
    throw e;
  }
}

// Decode with double-encoding detection
function decodeWithDetection(input) {
  const first = safeDecode(input);
  if (!first.success) return first;

  // Check if result still contains percent-encoded sequences
  const hasEncoded = /%[0-9A-Fa-f]{2}/.test(first.value);
  if (hasEncoded) {
    const second = safeDecode(first.value);
    return {
      ...second,
      wasDoubleEncoded: true,
      intermediateValue: first.value
    };
  }
  return { ...first, wasDoubleEncoded: false };
}

// Examples
console.log(safeDecode('hello%20world'));
// → { success: true, value: "hello world" }

console.log(safeDecode('%E2%9C%93'));
// → { success: true, value: "✓" }

console.log(decodeWithDetection('hello%2520world'));
// → { success: true, value: "hello world", wasDoubleEncoded: true }

Parsing form-encoded request body

// Decode application/x-www-form-urlencoded body
function parseFormBody(body) {
  const params = {};
  for (const pair of body.split('&')) {
    const [rawKey, ...rawValues] = pair.split('=');
    const key = decodeURIComponent(rawKey.replace(/\+/g, ' '));
    const value = decodeURIComponent(rawValues.join('=').replace(/\+/g, ' '));
    params[key] = value;
  }
  return params;
}

const body = 'name=John+Doe&city=S%C3%A3o+Paulo&q=a%26b%3Dc';
console.log(parseFormBody(body));
// → { name: "John Doe", city: "São Paulo", q: "a&b=c" }

Standards & Specifications

• RFC 3986 §2.1 — Defines percent-encoding and percent-decoding rules for URI characters
• WHATWG URL Standard — Specifies the percent-decode algorithm used by web browsers and the URL API