Encoding Pitfalls to Watch

Two web bugs traced to encoding: URL fragments in the URL API and window.btoa choking on non-ASCII.

Dec 16, 2020 · 1 min read · 207 Words · -Views -Comments · Programming
JavaScript 🇨🇳 阅读中文版
Read with AI

Choose an AI assistant

ChatGPT Open in a new tab with the article link and prompt
Claude Copy the prompt, then open Claude

Open Claude
Trouble reading the article?

If the prompt is missing, copy the full prompt below into your AI assistant. If the AI cannot read the article, paste the visible passage you want to discuss and add your question.

Recently I hit two frontend errors: SyntaxError: The URL must not contain a fragment and window.btoa throwing on input. Both stemmed from encoding gaps—easy to forget when frameworks usually handle them. Notes below for future reference.

Error screenshots

Background refresher

URI vs. URL

URI = Uniform Resource Identifier

URL = Uniform Resource Locator

Every URL is a URI, but not every URI is a URL. Example of a URI that isn’t a URL: mailto:alan@1991421.cn.

encodeURI vs. encodeURIComponent

JavaScript offers these helpers because certain characters in a URI have special meaning (: ; / ? : @ & = + $ , #, etc.). encodeURI leaves the separators intact; encodeURIComponent escapes everything, making it safer for query parameters.

window.btoa

See the MDN docs or my earlier post. btoa encodes binary strings to ASCII. Feed it characters outside Latin-1 (e.g., Chinese or Japanese) and it will throw unless you encode them first.

Fixes

  • When building URLs that include non-ASCII characters, encode the relevant parts before passing them to the URL constructor.
  • Before calling window.btoa, normalize the string (e.g., via encodeURIComponent) so it contains only ASCII.

Final Thoughts

Libraries like Axios hide these details, which is convenient but easy to misremember. Understanding the underlying rules makes debugging far less painful.

Authors
Developer, digital product enthusiast, tinkerer, sharer, open source lover