Error Handling and What Goes Wrong During Decryption
Decryption failures are designed to be obvious and informative in this utility. Because AES-256-GCM includes built-in authentication, the tool can reliably detect when something has gone wrong instead of silently producing incorrect or dangerous output. Understanding the common error messages helps you quickly identify and correct the issue without compromising security.
The most frequent message you will see is related to an incorrect passphrase. When the derived key does not match the one used during encryption, the authentication tag verification fails. The browser throws an OperationError, which the tool catches and displays as a clear warning: Decryption failed. Invalid ciphertext or wrong passphrase. This covers both mistyped passphrases and situations where the ciphertext was altered.
Other Common Causes
If the base64 string is incomplete or corrupted—perhaps cut off during copy-paste or modified by a text editor—the tool may fail early when trying to decode the string or extract the salt, initialization vector, and ciphertext. You will usually see a message indicating invalid base64 format or incorrect length. Always paste the full output exactly as generated, including any line breaks if they appear.
Another possibility is using a different browser or device that handles Web Crypto slightly differently, though this is rare with modern versions of Chrome, Firefox, Edge, and Safari. In those cases, the error is typically the same authentication failure message. The Web Crypto API is standardized, so cross-browser compatibility is excellent for AES-GCM operations.
Best Practices to Avoid Errors
Double-check the passphrase for exact spelling, capitalization, and spaces before decrypting. Copy the entire ciphertext in one go rather than selecting parts manually. If sharing via email or chat, consider sending the ciphertext as an attached text file to prevent accidental formatting changes. Test decryption immediately after encryption when possible to confirm everything works as expected.
Because the tool never guesses or weakens security to force a result, a failed decryption means the data is either inaccessible with the provided passphrase or has been damaged. There is no partial recovery—either the message decrypts perfectly or it does not decrypt at all. This all-or-nothing behavior is a deliberate security feature that prevents leaking information about partial guesses.
By paying attention to these error messages and following simple handling habits, you can use the utility confidently for both small notes and larger documents while maintaining the highest level of privacy and integrity.