Failed to load BIP39_MNEMONIC from keychain

[JeanlChristophe]

What happened?

Since the latest update, Bitkit shows the error Failed to load BIP39_MNEMONIC from keychain on launch (or shortly after). After that, nothing appears connected (e.g. Bitcoin node / network-related UI stays disconnected or unusable).

Expected behavior

• The mnemonic should load from the secure keychain / keystore.
• The wallet should initialize normally and node / network connectivity should work as before the update.

Steps to Reproduce

No response

Logs / Screenshots / Recordings

No response

Bitkit Version

2.2.0 (181)

Device / OS

Pixel 9

Reproducibility

None

Additional context

bitkit_logs_1776683442050.zip

[jvsena42]

What happened

You restored Bitkit's app data from a GrapheneOS transfer / Seedvault backup on 2026-04-02. The transfer copied Bitkit's encrypted recovery-phrase blob from the old install to the new one. However, AndroidKeyStore keys are hardware-bound and do not transfer across devices, flash cycles, or factory resets — on the new install, a fresh keystore key lives under the same alias. AES-GCM refuses to decrypt the old ciphertext under the new key, which is exactly what the new diagnostic shows:

WARN [Keychain.kt] Decrypt failed for key='BIP39_MNEMONIC' walletIndex='0'
     aliasPresent='true' entryPresent='true'
     causeChain='AEADBadTagException <- KeyStoreException'

aliasPresent='true' + entryPresent='true' + AEAD tag mismatch is the unambiguous fingerprint of "ciphertext and key were not produced by the same keystore."

v2.2.0 is not the cause

The log-file line-number fingerprints show the failure first appeared on v2.1.2, on 2026-04-02 — five days before v2.2.0 was tagged. v2.2.0 inherited the broken state; it didn't create it.

Funds status

Your funds are safe if you still have your written 12/24-word recovery phrase. On-chain UTXOs derive deterministically from the seed; Lightning channel state restores from the VSS backup Bitkit maintains during normal operation. The on-device encrypted copy of the phrase is cryptographically unrecoverable (AES-GCM under a lost key is unrecoverable by design).

Recovery steps

1. Confirm you have your backup phrase physically in hand before doing anything.
2. Settings → Recovery → Wipe App → confirm.
3. Reopen the app → Restore Wallet → enter your backup phrase.
4. Allow a few minutes for Lightning channel state to re-sync from VSS.

Do not tap Reset without your backup phrase. If the phrase is lost, on-chain funds on this install cannot be recovered.

For future transfers

Bitkit cannot be restored via Seedvault or any device-transfer tool — not on GrapheneOS, CalyxOS, or stock Android. Always migrate Bitkit by:

1. Backing up your 12/24-word recovery phrase (from Settings → Backup) before the transfer.
2. On the new device: install Bitkit fresh → Restore Wallet → enter the phrase.

This is a structural property of how Android keystore keys work (they're hardware-bound), not something a specific ROM or transfer tool can work around.

What we're shipping

• chore: log cause of keychain load failures #898 (merged): the diagnostic that surfaced the exact cause, so future occurrences are immediately identifiable.
• Next: an "installation sentinel" check that detects this mismatch at startup and routes users straight to a recovery screen with a clear warning — so nobody else lands on a silently broken app and panic-wipes without their seed.

[jvsena42]

postmortem_897.md