feat: add workarounds for database corruption scenarios (#39010)

## **Description**

This PR implements workarounds for Firefox database corruption issues
that cause `browser.storage.local` operations to fail with "An
unexpected error occurred".

### Problem
Firefox stores extension data in SQLite databases with external files
for large blobs. Some corruption scenarios, like [missing or renamed
external files (file IDs
mismatch)](#9196 (comment)),
can break these databases.

When this happens, `browser.storage.local.get()` or
`browser.storage.local.set()` fail entirely, leaving users locked out of
their wallet:
- #10091
- #35681

### Solution
This PR adds two recovery mechanisms:

1. **Vault Recovery on `get()` failure**: When
`browser.storage.local.get()` fails and a backup vault exists in
IndexedDB, users are redirected to the vault recovery flow to restore
their wallet.

2. **Informative Toast on `set()` failure**: When
`browser.storage.local.set()` fails (even after vault recovery), a
persistent toast is displayed informing users that the storage is
failing and MetaMask needs to be reinstalled. The toast includes a link
to save the Secret Recovery Phrase before reinstalling.

[Slack
thread](https://consensys.slack.com/archives/C8RSKCNCD/p1766165879957189?thread_ts=1764958704.459329&cid=C8RSKCNCD)

### Out of scope for this PR
- Add instrumentation (Sentry or Segment)
- Instrumentation will be added in a different PR:
#39113
- Add new scenarios to storage corruption E2E tests.
- Storage corruption E2E tests are currently disabled (cf. this ticket:
#38080).
- We'll wait until Accounts team enables BIP44 by default in the
codebase (it's currently enabled enabled using a feature flag) before
re-enabling storage corruption E2E tests. Otherwise these tests would be
flaky (cf. this [Slack
thread](https://consensys.slack.com/archives/C01U65ZUS2E/p1767717796349449?thread_ts=1767634209.723779&cid=C01U65ZUS2E)).

[![Open in GitHub
Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MetaMask/metamask-extension/pull/39010?quickstart=1)

## **Changelog**

CHANGELOG entry: Fixes Firefox database corruption causing "An
unexpected error occurred" by redirecting to vault recovery when
possible, or displaying guidance to reinstall when recovery is not
possible.

## **Related issues**

Fixes: #10091
Fixes: #35681

## **Manual testing steps**

### Prerequisites
- Firefox browser
- MetaMask installed from Firefox Add-ons store (or local build with
`yarn dist:mv2`)
- The `test-vault-corruption-firefox.sh` script from this
[PR](#38940)

### Test 1: Vault Recovery flow started on storage `get()` failure

1. Install MetaMask and complete onboarding
2. Close Firefox completely
3. Run `./test-vault-corruption-firefox.sh` and select option **5**
(Rename files off-by-one)
4. Open Firefox and click the MetaMask icon
5. **Expected**: You should see the vault recovery screen with "Restore
Accounts" button
6. Click "Restore Accounts", enter your password, complete onboarding
7. **Expected**: Wallet is restored with original accounts

### Test 2: Toast displayed on storage `set()` failure

8. **Expected**: A toast is displayed: "We couldn't save your data -
Back up your Secret Recovery Phrase and reinstall MetaMask if the
problem continues."
9. Click "Back up Secret Recovery Phrase"
10. **Expected**: You are navigated to the SRP reveal page

## **Screenshots/Recordings**

### **Before**

Users see "An unexpected error occurred" with no recovery path.
<img width="426" height="410" alt="Screenshot 2026-01-05 at 06 07 46"
src="https://github.com/user-attachments/assets/a888167c-55ce-4e80-9d83-a53058df06b5"
/>

### **After**

1. **Vault Recovery Flow** (when reads fail):
- Users see the vault recovery screen and can restore their wallet (when
backup exists)
<img width="384" height="578" alt="Screenshot 2026-01-03 at 16 07 30"
src="https://github.com/user-attachments/assets/f64cc4e1-e3ea-4d5a-a635-93cdf687835e"
/>

2. **Storage Error Toast** (when writes fail):
   - Toast appears with message: "We couldn't save your data"
- Description: "Back up your Secret Recovery Phrase and reinstall
MetaMask if the problem continues."
- Action button: "Back up Secret Recovery Phrase" → navigates to SRP
reveal
<img width="1521" height="749" alt="Screenshot 2026-01-07 at 23 14 01"
src="https://github.com/user-attachments/assets/e65be4c1-9dd2-492c-b689-13ebf86c6053"
/>

[Loom
recording](https://www.loom.com/share/d51c11812db54a9d8aa29465798bdd33)

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask
Extension Coding
Standards](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [ ] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **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.






<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces recovery UX and error signaling for storage failures, plus
improved error context.
> 
> - Persistence: Enhance `PersistenceManager.get()` to handle
`storage.local.get` errors, trigger vault recovery via
`PersistenceError` (now includes `cause`) when an IndexedDB backup
exists; on `set` failures, notify UI via a new `setOnSetFailed` callback
(background wires this to
`AppStateController.setShowStorageErrorToast(true)`).
> - State/Types: Add `appState.showStorageErrorToast` (non-persisted)
and expose in Sentry snapshots and background types.
> - UI: Add `StorageErrorToast` rendered globally in `ToastMaster`
(gated by `selectShowStorageErrorToast`), with action to navigate to SRP
reveal; add i18n strings for title/description/action.
> - Error delivery: In state-corruption handling, include `causeMessage`
from `PersistenceError.cause` when notifying UI.
> - Tests/fixtures: Update unit/e2e/integration snapshots and mocks to
cover new flags, behaviors, and logging.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
03a318d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: gauthierpetetin

app/_locales/en/messages.json

@@ -131,7 +131,7 @@ global.stateHooks.getStorageKind = () => persistenceManager.storageKind;
 
 /**
  * A helper function to log the current state of the vault. Useful for debugging
- * purposes, to, in the case of database corruption, an possible way for an end
+ * purposes, to, in the case of storage errors, a possible way for an end
  * user to recover their vault. Hopefully this is never needed.
  */
 global.logEncryptedVault = () => {
@@ -1223,6 +1223,11 @@ export function setupController(
     cronjobControllerStorageManager,
   });
 
+  // Wire up the callback to notify the UI when set operations fail
+  persistenceManager.setOnSetFailed(() => {
+    controller.appStateController.setShowStorageErrorToast(true);
+  });
+
   /**
    * @type {Array<string>} List of controller store keys that have changed since initialization.
    */

app/_locales/en_GB/messages.json

@@ -93,6 +93,7 @@ export const SENTRY_BACKGROUND_STATE = {
     lastUpdatedAt: true,
     shieldEndingToastLastClickedOrClosed: true,
     shieldPausedToastLastClickedOrClosed: true,
+    showStorageErrorToast: true,
     isWalletResetInProgress: false,
     pna25Acknowledged: false,
   },

app/scripts/background.js

@@ -807,6 +807,7 @@ describe('AppStateController', () => {
               "showNetworkBanner": true,
               "showPermissionsTour": true,
               "showShieldEntryModalOnce": null,
+              "showStorageErrorToast": false,
               "showTestnetMessageInDropdown": true,
               "sidePanelGasPollTokens": [],
               "signatureSecurityAlertResponses": {},
@@ -900,6 +901,7 @@ describe('AppStateController', () => {
               "showNetworkBanner": true,
               "showPermissionsTour": true,
               "showShieldEntryModalOnce": null,
+              "showStorageErrorToast": false,
               "showTestnetMessageInDropdown": true,
               "sidePanelGasPollTokens": [],
               "signatureSecurityAlertResponses": {},
@@ -1073,6 +1075,7 @@ describe('AppStateController', () => {
               "showNetworkBanner": true,
               "showPermissionsTour": true,
               "showShieldEntryModalOnce": null,
+              "showStorageErrorToast": false,
               "sidePanelGasPollTokens": [],
               "signatureSecurityAlertResponses": {},
               "slides": [],

app/scripts/constants/sentry-state.ts

@@ -166,6 +166,12 @@ export type AppStateControllerState = {
    * Whether the wallet reset is in progress.
    */
   isWalletResetInProgress: boolean;
+
+  /**
+   * Whether to show the storage error toast.
+   * This is set to true when set operations fail (storage.local or IndexedDB).
+   */
+  showStorageErrorToast: boolean;
 };
 
 const controllerName = 'AppStateController';
@@ -326,6 +332,7 @@ const getDefaultAppStateControllerState = (): AppStateControllerState => ({
   pendingShieldCohortTxType: null,
   isWalletResetInProgress: false,
   dappSwapComparisonData: {},
+  showStorageErrorToast: false,
   ...getInitialStateOverrides(),
 });
 
@@ -711,6 +718,12 @@ const controllerMetadata: StateMetadata<AppStateControllerState> = {
     includeInDebugSnapshot: false,
     usedInUi: true,
   },
+  showStorageErrorToast: {
+    includeInStateLogs: true,
+    persist: false,
+    includeInDebugSnapshot: true,
+    usedInUi: true,
+  },
 };
 
 export class AppStateController extends BaseController<
@@ -938,6 +951,18 @@ export class AppStateController extends BaseController<
     });
   }
 
+  /**
+   * Sets whether to show the storage error toast.
+   * This is called when set operations fail (storage.local or IndexedDB).
+   *
+   * @param show - Whether to show the toast
+   */
+  setShowStorageErrorToast(show: boolean): void {
+    this.update((state) => {
+      state.showStorageErrorToast = show;
+    });
+  }
+
   /**
    * Replaces slides in state with new slides. If a slide with the same id
    * already exists, it will be merged with the new slide.

app/scripts/controllers/app-state-controller.test.ts

@@ -43,6 +43,10 @@ const mockBrokenPersistence = (error: Error): PersistenceManager =>
     getBackup: jest.fn().mockRejectedValue(error),
   }) as unknown as PersistenceManager;
 
+// The cause error message that is always included in PersistenceError
+// to test that causeMessage is properly extracted and passed to the UI
+const CAUSE_ERROR_MESSAGE = 'Error: An unexpected error occurred';
+
 describe('CorruptionHandler.handleStateCorruptionError', () => {
   let corruptionHandler: CorruptionHandler;
   beforeEach(() => {
@@ -107,10 +111,14 @@ describe('CorruptionHandler.handleStateCorruptionError', () => {
 
         // some cases of Corruption detection will have a `backup` already
         // present in the `error` object, this sets that case up.
+        // We always include a cause to test that causeMessage is properly
+        // extracted and passed to the UI across all scenarios.
+        const cause = new Error(CAUSE_ERROR_MESSAGE);
         const error = new PersistenceError(
           'Corrupted',
           // `backup` is not always a `Backup`, but in reality that is also true
           backupHasErr ? (backup as Backup) : null,
+          cause,
         );
 
         // handle the case where `getBackup` function returns an error. We can't
@@ -172,12 +180,13 @@ describe('CorruptionHandler.handleStateCorruptionError', () => {
         );
 
         // make sure the `corruptionFn` was called with the expected error
-        // message
+        // message, including the causeMessage extracted from the cause
         expect(corruptionFn).toHaveBeenCalledWith({
           error: {
             message: error.message,
             name: error.name,
             stack: error.stack,
+            causeMessage: CAUSE_ERROR_MESSAGE,
           },
           ...result,
         });

app/scripts/controllers/app-state-controller.ts

@@ -3,7 +3,11 @@ import {
   METHOD_DISPLAY_STATE_CORRUPTION_ERROR,
   METHOD_REPAIR_DATABASE,
 } from '../../../../shared/constants/state-corruption';
-import { type Backup, PersistenceManager } from '../stores/persistence-manager';
+import {
+  type Backup,
+  PersistenceError,
+  PersistenceManager,
+} from '../stores/persistence-manager';
 import { ErrorLike } from '../../../../shared/constants/errors';
 import { tryPostMessage } from '../start-up-errors/start-up-errors';
 import { RELOAD_WINDOW } from '../../../../shared/constants/start-up-errors';
@@ -102,6 +106,25 @@ function maybeGetCurrentLocale(backup: Backup | null): string | null {
   return null;
 }
 
+/**
+ * Attempts to get the cause message from a PersistenceError.
+ * This provides additional context about the original error that caused
+ * the persistence failure (e.g., Firefox's "Error: An unexpected error occurred").
+ *
+ * @param error - The error to extract the cause message from.
+ * @returns The cause message if available, otherwise null.
+ */
+function maybeGetCauseMessage(error: ErrorLike): string | null {
+  if (
+    error instanceof PersistenceError &&
+    error.cause instanceof Error &&
+    error.cause.message
+  ) {
+    return error.cause.message;
+  }
+  return null;
+}
+
 /**
  * Checks if the backup object has a vault.
  *
@@ -156,13 +179,17 @@ export class CorruptionHandler {
     // it is not worth claiming we have a backup if the vault doesn't actually
     // exist
     const hasBackup = Boolean(hasVault(backup));
+    // Extract cause message if available (e.g., Firefox's "Error: An unexpected error occurred")
+    // This helps users and customer support debug issues
+    const causeMessage = maybeGetCauseMessage(error);
 
     // send the `error` to the UI for this port
     const sent = tryPostMessage(port, METHOD_DISPLAY_STATE_CORRUPTION_ERROR, {
       error: {
         message: error.message,
         name: error.name,
         stack: error.stack,
+        causeMessage,
       },
       currentLocale,
       hasBackup,

app/scripts/lib/state-corruption/state-corruption-recovery.test.ts

@@ -21,6 +21,7 @@ jest.mock('./extension-store', () => {
 });
 jest.mock('loglevel', () => ({
   error: jest.fn(),
+  info: jest.fn(),
 }));
 jest.mock('../../../../shared/lib/sentry', () => ({
   captureException: jest.fn(),
@@ -109,14 +110,14 @@ describe('PersistenceManager', () => {
 
   describe('get', () => {
     it('returns undefined and clears mostRecentRetrievedState if store returns empty', async () => {
-      mockStoreGet.mockReturnValueOnce({});
+      mockStoreGet.mockResolvedValueOnce({});
       const result = await manager.get({ validateVault: false });
       expect(result).toBeUndefined();
       expect(manager.mostRecentRetrievedState).toBeNull();
     });
 
     it('returns undefined if store returns null', async () => {
-      mockStoreGet.mockReturnValueOnce(null);
+      mockStoreGet.mockResolvedValueOnce(null);
       const result = await manager.get({ validateVault: false });
       expect(result).toBeUndefined();
       expect(manager.mostRecentRetrievedState).toBeNull();