fix: wrap vault backup initial read in try/catch to survive Android Keystore key invalidation

[tommasini]

---

Description

Reason for the change:

On Android, when a user changes their biometric enrollment (or due to an Android 16 Keystore behavioral change), the Keystore key backing the vault backup entry can be permanently invalidated. In that state, getInternetCredentials(VAULT_BACKUP_KEY) throws an exception rather than returning false/undefined. Because that call sat inside the outer try/catch in backupVault, the thrown error was caught at the top-level catch, which logged "Vault backup failed" to Sentry and returned { success: false } — even though the underlying vault was fine and a fresh backup could have been written successfully.

Solution:

Wrap the initial getInternetCredentials read in its own inner try/catch. If the read throws (key invalidated), we:

1. Log a non-error warning via Logger.log (no Sentry noise)
2. Clear any corrupted keychain entries with clearAllVaultBackups()
3. Fall through to write a fresh backup normally

This makes backupVault resilient to stale Android Keystore state and prevents a false "Vault backup failed" from ever surfacing when the real backup operation can succeed.

Changelog

CHANGELOG entry: Fixed an issue on Android where vault backup could silently fail after a biometric enrollment change or Keystore key invalidation

Related issues

No issue: bug surfaced via Sentry report (extra.message: "Vault backup failed") — Android Keystore key invalidation causing getInternetCredentials to throw inside backupVault

Manual testing steps

Feature: Vault backup resilience on Android

  Scenario: Vault backup succeeds even when existing backup read throws due to Keystore invalidation
    Given the user has a MetaMask wallet set up on Android
    And a vault backup already exists in the keychain
    And the Android Keystore key has been invalidated (e.g. by adding/removing biometric enrollment)

    When the vault backup routine is triggered (e.g. on wallet unlock or state change)
    Then the backup should complete successfully
    And no "Vault backup failed" error should appear in Sentry
    And the user should not be prompted with an error or crash

Note: This fix is primarily defensive for an Android Keystore edge case. Manual reproduction requires a device where biometrics have been changed after the backup was created, or an Android 16 device exhibiting the Keystore regression. Unit test coverage added for the throwing path.

Screenshots/Recordings

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Made with Cursor

---

Note

Low Risk
Low risk, localized change that only alters error handling around reading existing keychain credentials and adds a unit test for the throwing path. Main risk is potentially masking unexpected read failures by proceeding to overwrite the backup.

Overview
Makes backupVault resilient to Android Keystore/keychain read exceptions by wrapping the initial getInternetCredentials(VAULT_BACKUP_KEY) call in an inner try/catch and proceeding as if no existing backup was found (while logging via Logger.log).

Adds a unit test ensuring vault backup still reports success when the existing-backup read throws (simulating Android Keystore key invalidation).

^{Reviewed by Cursor Bugbot for commit 6a6edf9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[Cal-L]

Left a comment

[Cal-L]

LGTM

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 43ff1dd. Configure here.}

[cursor]

Test name uses banned "should" prefix

Low Severity

The new test name 'should still succeed if reading the existing backup throws...' uses the word "should", which is banned per the unit testing guidelines ("NEVER use 'should' in test names — this is a hard rule with zero exceptions"). An action-oriented alternative like 'completes backup when reading existing backup throws due to Keystore key invalidation' would conform to the rule.

 

^{Triggered by project rule: Unit Testing Guidelines}

^{Reviewed by Cursor Bugbot for commit 43ff1dd. Configure here.}

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are a targeted defensive bug fix in app/core/BackupVault/backupVault.ts:

1. What changed: The backupVault() function now wraps the getInternetCredentials(VAULT_BACKUP_KEY) call in its own try/catch. This handles Android Keystore key invalidation scenarios (biometric enrollment changes, Android 16 behavioral changes) where the API throws instead of returning false/undefined. On error, it logs and treats the situation as "no existing backup," allowing the fresh backup write to proceed.

2. Scope: Purely a defensive error-handling addition. The happy path is completely unchanged. No UI, navigation, controller state, or shared component changes.

3. Test coverage: A new unit test was added in backupVault.test.ts that directly validates the new behavior by mocking getInternetCredentials to throw and asserting the backup still succeeds.

4. E2E relevance: No E2E test tag covers Android Keystore invalidation scenarios — this is a device-level edge case that unit tests are the appropriate vehicle for. The change doesn't affect any flows tested by the available E2E tags (confirmations, swaps, accounts, identity, network, browser, snaps, etc.).

5. Risk: Low. The fix is additive (adds error resilience), doesn't change behavior on the success path, and is well-covered by the new unit test.

No E2E tags are warranted for this change.

Performance Test Selection:
The change is a defensive error-handling fix in the vault backup read path. It adds a try/catch around a single keychain read operation. There is no UI rendering, no list components, no state management changes, and no impact on app startup or critical user flows that would affect performance metrics.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud