Encoding Pitfalls to Watch
Recently I hit two frontend errors:
SyntaxError: The URL must not contain a fragment
andwindow.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., viaencodeURIComponent
) 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.