Fix malformed percent-encoded UTF-8
A URL value reaches your app, but decodeURIComponent() throws URIError. Before replacing punctuation, separate two failures: an incomplete percent escape and a complete byte escape that is not valid UTF-8.
Find the boundary where the value changes
Suppose a search box accepts 50% off, but opening the resulting link crashes the page. The percent sign is ordinary text in the search box. It becomes special only when code treats that text as an already-encoded URL component. Write down the expected value at each boundary: the user's text, the serialized URL, and the value read by the receiving page. You are looking for an encoding mismatch, not punctuation to delete.
Use a harmless sample rather than copying a real password-reset link or customer query into a console or public issue. First try decodeURIComponent("%25"): the expected result is a single percent sign. Then try the failing sample using the guarded helper in “Reject malformed input without crashing the page” below. If the valid control works while the sample fails, the decoder is not universally broken; the supplied data needs investigation.
Distinguish a broken escape from invalid UTF-8
A bare % has no two-digit byte value. By contrast, %92 is syntactically a byte escape, but that byte cannot stand alone in UTF-8. Public reports show both mistakes, including legacy quote bytes and an isolated %AF.
decodeURIComponent("%"); // URIError
decodeURIComponent("%92"); // URIError
decodeURIComponent("%25"); // %
decodeURIComponent("%C2%AF"); // ¯
decodeURIComponent("%E2%80%99"); // ’
The retained Node v24.19.0 fixture reproduced these outcomes and also tested %91, %AF and the UTF-8 left quote. Browser wording may differ; success or rejection of the exact input is the useful evidence.
Build query strings without hand-joining percent escapes
For a new link, pass the original text to the URL API and let it serialize the parameter. On the receiving side, read that parameter through the same API. Do not immediately decode the returned value again:
const link = new URL("https://example.com/search");
link.searchParams.set("q", "50% off & café");
const received = new URL(link.href).searchParams.get("q");
console.log(received); // 50% off & café
This is an example URL, not a FrAIFlow endpoint. The important distinction is between an encoded component and a value that has already been parsed. A second decoding pass can turn perfectly legitimate text such as 50% off into an exception. Also remember that a plus sign in form-style query parameters has different handling from a literal plus passed directly to decodeURIComponent(); use the parser that matches the format.
Correct the producer rather than guessing characters
Keep the exact failing sample privately and ask the producer what character encoding it used. A lonely %92 may suggest a legacy byte convention, but the byte alone does not establish its origin. Do not silently substitute an apostrophe in account IDs, signatures or filenames. Return a useful error, preserve the original input for the user, and correct the encoding at the source when possible.
After the change, test a literal percent, an accented word, a curly quote, a plus sign and an ampersand. Each value should survive a complete create-link → open-link → read-value round trip unchanged. Malformed input should produce your controlled error rather than stop the rest of the page. These checks verify your format contract; they do not justify repeatedly decoding until a string looks readable.
Reject malformed input without crashing the page
function decodeComponent(value) {
try { return { ok: true, value: decodeURIComponent(value) }; }
catch (error) {
if (!(error instanceof URIError)) throw error;
return { ok: false, error: "Invalid encoded component" };
}
}
This boundary reports failure without silently changing an identifier. It cannot discover an unknown source encoding. Decode only as often as the format contract requires: a percent sign remaining after a successful decode does not justify another pass. Avoid deprecated unescape() as a UTF-8 fix, and keep tokens or private query values out of public diagnostic logs.
