feat: add workarounds for database corruption scenarios

app/scripts/background.js

@@ -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 = () => {
@@ -1209,6 +1209,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/scripts/constants/sentry-state.ts

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

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

@@ -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/controllers/app-state-controller.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/lib/state-corruption/state-corruption-recovery.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/lib/state-corruption/state-corruption-recovery.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/stores/persistence-manager.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();