SecureStorageFailure enum

One entry's bytes cannot be decrypted. The store itself is healthy.

The entry will never become readable again, so dropping it is the recovery — and SecureStorageService performs it for you: read answers null, containsKey answers false, readAll answers {}, after announcing the deletion on SecureStorageService.onBeforeRecoveryDelete. You only see this value if you classify an error you caught from somewhere else.

The store's own key is unusable, so nothing in it can be read, written or deleted through the plugin — including the deletion that would "repair" it.

SecureStorageService never deletes on this, and never answers null: it rethrows, because there is no state it could put you in that would be truthful. What to do is yours to decide, and the two useful moves are:

• retry once. Plugin 10.x only, read in its Android sources (10.0.0 to 10.3.4) rather than measured: when the failure comes from missing algorithm markers, StorageCipherFactory writes the current markers as it builds, so the next call no longer takes that branch and the failure clears itself. From 11.0 a store without markers is taken to use the current algorithms, and that branch cannot fail at all.
• treat a second failure as permanent. When the markers are present but no longer match the key, nothing is rewritten and every call fails identically until the store is reset — pass your own FlutterSecureStorage with resetOnError: true, which is the plugin's own recovery for this, knowing what SecureStorageService gives up by disabling it (see the constructor).

⚠️ A restored backup produces it — the one field trigger reproduced so far. Android Auto Backup brings the plugin's preference files back after a reinstall or on a new phone — the data, the markers and the wrapped key — but not the Keystore key that wrapped it, which never leaves the device. Every call then fails with Migration failed after algorithm change (Invalid key, key type incompatible with cipher), on every launch, and a retry never clears it. Measured on an Android 11 (API 30) emulator at plugin 10.3.1 and 11.2.0 (2026-09-24), and so was the purge below: it resets the store, and the next process writes again. A "clear app data" does not produce this state — measured the same day, it removes the Keystore key along with the preferences, and the next launch starts from an empty store. Prevent it rather than recover from it: exclude the plugin's files from backup, as the README shows.

⚠️ One envelope, several causes. Migration failed after algorithm change (…) is also what a withBiometrics() refusal looks like — from the first call on an Android 11 (API 30) emulator with no lock screen, BIOMETRIC_UNAVAILABLE buried in the Caused by: chain. No retry and no purge clears that one: the device has nothing to prompt for. The (%s) narrows it down — Invalid key, … for a restored backup, Algorithm changed detected for that refusal as for markers naming another algorithm — but only the Caused by: chain says for sure, and it travels in SecureStorageRecovery.error and in the exception you catch.

⚠️ That purge instance has to name the same store to reach anything, and from plugin 10.2.0 the first successful call for a store — and key prefix, from 11.2.0 — fixes its options for the process. So its resetOnError: true governs apix's calls afterwards too: SecureStorageService.onBeforeRecoveryDelete goes quiet, and up to 10.2.x a write that fails after a broken initialisation comes back as a success. Restart the process after purging rather than carrying on inside it — the same advice as SecureStorageService.withBiometrics.

Do not catch this and keep writing: see SecureStorageService.withBiometrics for what a plugin left without a cipher does to the next write.

Anything else — a cancelled biometric prompt, a locked keychain, a missing plugin, a network or parsing failure that happened to travel through here. Rethrown untouched, and never a reason to delete anything.