flutter_secure_storage: Migrating from v8 to v11 (Data Loss Analysis & Fix)

Source: https://pub.dev/packages/flutter_secure_storage/changelog (latest at time of writing: 11.2.0, 2026-09-16)

---

1. Problem

After updating an existing app from flutter_secure_storage v8 to v11, data written by v8 can no longer be read.

2. Root cause

v8 → v11 is an unsupported direct jump. The v11.0.0 changelog states that items deprecated in v10 were removed, that data saved with deprecated algorithms or features becomes unusable, and that anyone on a version before v10 must upgrade to v10 first so existing data is migrated.

Android changes across versions

Version	Change	Effect on v8 data
v8 (defaults)	Key cipher RSA_ECB_PKCS1Padding, storage cipher AES_CBC_PKCS7Padding (or encryptedSharedPreferences: true if you enabled it)	This is how your data is stored
v10.0.0	Defaults changed to RSA_ECB_OAEPwithSHA_256andMGF1Padding and AES_GCM_NoPadding. migrateOnAlgorithmChange migrates old data. resetOnError now defaults to true. Jetpack EncryptedSharedPreferences replaced with custom ciphers (auto-migrated). minSdk 19 → 23.	Migrated only if the app runs v10
v10.1.0	Added storageNamespace (full isolation) and migrateWithBackup (crash-resistant migration). sharedPreferencesName deprecated.	Still readable
v10.2.0	RSA_ECB_PKCS1Padding and AES_CBC_PKCS7Padding deprecated. Auto-migrated when migrateOnAlgorithmChange is true.	Still readable
v10.3.x	Biometric options, iOS/Windows/Linux fixes	n/a
v11.0.0	Removed RSA_ECB_PKCS1Padding, AES_CBC_PKCS7Padding, encryptedSharedPreferences, sharedPreferencesName. minSdk 24, compileSdk 37.	Old format cannot be read
v11.1.0	Added checkUpgradeStatus(). Fixed moving the wrapped key when switching between sharedPreferencesName and storageNamespace.	Detection and partial recovery help
v11.2.0	Android recovery fixes (namespace switch, biometric key recovery, deleteAll scoped to key prefix). Darwin: find keychain items across accessibility levels.	Recommended minimum for v11

The dangerous part: resetOnError

Since v10, resetOnError defaults to true. When v11 cannot decrypt old v8 data, it treats this as an unrecoverable error and wipes the storage and keys. That is why the data may be permanently gone for users who already made the direct jump.

---

3. The fix: upgrade in two releases

Release 1: bridge version (v10)

pubspec.yaml:

dependencies:
  flutter_secure_storage: ^10.3.1   # latest 10.x listed in the changelog; confirm on the Versions tab

Initialization:

const storage = FlutterSecureStorage(
  aOptions: AndroidOptions(
    migrateOnAlgorithmChange: true, // default, set explicitly
    migrateWithBackup: true,        // added in 10.1.0, backup if migration crashes
    // resetOnError: false,         // optional: avoid wiping data during the bridge release
  ),
);

Force migration on every launch of the bridge release:

Future<void> triggerMigration() async {
  await storage.readAll(); // initialization and migration happen on first access
}

Call it early in main(). Keep this release live long enough for most active users to open it.

Release 2: v11

Ship only after the bridge release has been out for a while.

Checklist:

1. Remove encryptedSharedPreferences and sharedPreferencesName from AndroidOptions (the build fails otherwise).
2. If you used sharedPreferencesName, switch to storageNamespace. v11.1.0 added a fix to move the wrapped key when switching. The changelog does not describe the exact behaviour, so test this path on a real upgrade.
3. Raise minSdk to 24 and align compileSdk/targetSdk with the plugin. Use Java 17.
4. Use v11.2.0 or later.

dependencies:
  flutter_secure_storage: ^11.2.0

---

4. If you already shipped v11

• Users still on v8: do not let them jump. Ship the v10 bridge first and push them to update to it.
• Users who already upgraded: if the wipe happened, the data is not recoverable through the plugin. The only technical route is a custom native Kotlin migration that decrypts the old format, which is hard to get right. The practical route is to treat them as logged out, have them re-authenticate, or restore secrets from your backend.

---

5. iOS / macOS

Keychain data normally survives upgrades, but v10 merged iOS and macOS into the flutter_secure_storage_darwin package. To keep data readable:

• Keep the same IOSOptions as in v8: accountName (kSecAttrService), accessibility, groupId, synchronizable. A mismatch makes items look missing.
• Since v10.3.0, kSecUseDataProtectionKeychain is only set when useDataProtectionKeychain is explicitly enabled. If you did not set it before, do not set it now.
• v11.2.0 added a fix to find keychain items across accessibility levels.
• The minimum iOS version is now 12 (macOS 10.14).

---

6. Detecting loss in v11

v11.1.0 added checkUpgradeStatus(), which reports data lost on a direct major upgrade. Call it on first launch after upgrading to decide whether to prompt the user to log in again. The exact return type was not verified, so check the API reference before coding against it.

Recommended fallback: if a required key reads as null after upgrade, treat the user as logged out and re-authenticate instead of crashing.

---

7. Testing procedure

1. Build an app with v8 and your exact v8 options, then write real test values.
2. Install the v10 build over it (do not uninstall), launch, and confirm the values are readable.
3. Install the v11 build over that and confirm again.
4. Repeat from v8 straight to v11 to reproduce the loss for yourself.
5. Test on Android 7–8, 10 and 13+, since Keystore behaviour varies.

---

8. Quick summary

• Cause: v11 removed the ciphers and backends v8 used; v10 was the only version that migrates them.
• Fix: v8 → v10 (with migration, run on every launch) → v11.
• Risk: resetOnError: true wipes data when decryption fails.
• iOS: keep the same IOSOptions.
• Detection: checkUpgradeStatus() (v11.1.0+).