Wasabi Wallet - Total Privacy For Bitcoin

"Compatibility passphrase was used! Please consider generating a new wallet to ensure recoverability!"

If Wasabi has been displaying that message to you for the last 5 years, well… it's time to take action.

tl;dr

Because of a clipboard bug on macOS (OSX) in the Avalonia UI framework, users who created wallets by pasting complex passwords (with non-ASCII characters) got their password silently corrupted. When they later tried to log in by typing the correct password, it didn't match.

When a user enters their passphrase, if it is incorrect, Wasabi derives the corrupted passphrase and tries that one instead — in case of success, it alerts the user with the warning message above. We assume that after 5 years without any news about this issue, no one is affected. We will still give months before removing it.

Long version:

Some users were locked out of their wallets after updating Wasabi because the password they entered when logging in didn't match the password stored in the wallet file.

The Root Cause

There was a clipboard bug on macOS (OSX) in the Avalonia UI framework. When a user pasted a password from the clipboard:

1. Avalonia retrieved the clipboard content as raw bytes plus a "size" value.
2. The size was incorrectly taken from the string length (number of characters) instead of the byte length.
3. This matters because UTF-8 encoding uses variable bytes per character — special characters (like ä, ö, ñ, ¾) use 2–4 bytes each, while ASCII characters use 1 byte.

Example: A password like "Café" has 4 characters but takes 5 bytes in UTF-8 (C-a-f-é, where é = 2 bytes). The buggy code would only read 4 bytes, giving "Caf" plus a partial/corrupted character.

What Happened

Users who created wallets by pasting complex passwords (with non-ASCII characters) got their password silently truncated and corrupted. The wallet was created with the buggy password, but when they later tried to log in by typing the correct password, it didn't match.

The Fix

The compatibility feature tries multiple password variations when logging in:

1. The exact password entered.
2. The "buggy clipboard" version (truncated to string length in bytes).
3. A variant where the last character might be the replacement character \ufffd.

If the original password fails but a buggy variant works, the user is warned:
"Compatibility passphrase was used! Please consider generating a new wallet to ensure recoverability!"

This allows affected users to access their funds while warning them that their wallet was created with a corrupted password (which would be unrecoverable using standard BIP39 tools).