Encoding Pitfalls to Watch

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.