Base64 Pitfalls: btoa Errors, Missing Padding, URL-Safe Variants and Size Surprises

Base64 turns arbitrary bytes into 64 safe, printable characters so that binary data can pass through systems designed for text, such as JSON, email and URLs. Every three bytes become four characters. It is an encoding, not encryption. There is no key, and anyone can decode it, so never use it to hide a password or a secret.

In browsers, btoa accepts only characters whose code is below 256. Passing a string with é might work by accident, and passing a euro sign, an emoji or Chinese text throws an InvalidCharacterError. The function treats a string as a sequence of bytes, so you must turn the text into UTF-8 bytes yourself first.

• ▸Encode: convert the string to bytes with TextEncoder, turn each byte into a character, and give the result to btoa.
• ▸Decode: call atob, turn each character into its byte value, and decode the bytes with TextDecoder using UTF-8.
• ▸Without that step, decoded text shows as garbled characters like é, which is the same family of bug covered in our guide to broken encodings.
• ▸Newer runtimes also offer direct conversion helpers for byte arrays, but the TextEncoder approach works everywhere.

• ▸Padding removed. Base64 output is padded with equals signs to a multiple of four characters. Some systems strip the padding, notably JSON Web Tokens. Add equals signs until the length is a multiple of four before decoding.
• ▸URL-safe alphabet. The standard alphabet uses plus and slash, which are special in URLs. The URL-safe variant uses hyphen and underscore instead. Feeding one alphabet to a strict decoder for the other fails. Convert the characters, or use a decoder that accepts both.
• ▸Whitespace and line breaks. Email formats wrap Base64 at 76 characters. Strip all whitespace before decoding.
• ▸Data URL prefix. A string like data:image/png;base64, followed by the data must have the prefix removed before decoding.
• ▸The result is binary. If the original was an image or a compressed file, decoding to text gives garbage by design. Treat the bytes as bytes and write them to a file or a blob.

Four output characters for every three input bytes means a 33 percent increase, plus padding and any line breaks. A 3 MB image becomes about 4 MB of text, and if that text is placed in JSON that is then compressed with gzip, the gain from compression is smaller than for the raw file. For large files, send them as binary with multipart upload or a direct storage upload, and keep Base64 for small payloads such as icons and tokens.

• ▸HTTP Basic authentication: the header carries username and password joined by a colon and encoded. It is not protection, so Basic authentication must always travel over HTTPS.
• ▸JSON Web Tokens: Base64URL without padding for the header, payload and signature.
• ▸Data URLs: small images inlined in HTML or CSS. Fine for tiny assets, but they cannot be cached separately and inflate the page.
• ▸Binary fields in JSON APIs: acceptable for small blobs, with the cost described above.
• ▸Email attachments: the standard way to carry binary in a text protocol.

Look at the length: is it a multiple of four? Look at the characters: are there plus or slash characters, or hyphen and underscore? Is there a prefix or whitespace? Decode a small sample in the Base64 Encoder and Decoder, which accepts both alphabets, adds missing padding and decodes as UTF-8. If the result is unreadable, the data is probably binary and the next step is a file, not a string.