Fixing Common Flutter Security Plugin Errors

Flutter security plugins are essential for protecting sensitive data, but they can be frustrating when they fail silently or throw cryptic errors. I’ve spent more hours than I’d like chasing down keychain exceptions and missing plugin registrations. Let me share the most common issues and how to fix them — so you spend less time debugging and more time building.

Why Do Flutter Security Plugins Fail?

Security plugins in Flutter often rely on platform-specific APIs (Keychain on iOS, EncryptedSharedPreferences on Android). The main failure points are:

• Missing platform configuration – iOS requires Keychain Sharing entitlement; Android needs a minimum SDK version.
• Plugin registration errors – When using Swift or Kotlin, the plugin must be registered in the AppDelegate or MainActivity.
• Encryption key mismanagement – Using a key of the wrong length or algorithm.
• Database or storage corruption – Especially when migrating from an older version of the plugin.

Many of these problems appear only on real devices or after a release build.

flutter_secure_storage: The Most Common Culprit

The flutter_secure_storage package is widely used but has platform-specific gotchas. Here’s what to check when it fails.

Android: NoSuchMethodError or Null Return

On Android, if you get a NoSuchMethodError or the storage returns null, you’re probably missing the minimum SDK version. Add this to your android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 18
    }
}

Also ensure you’re not using a version of the plugin that’s incompatible with your Flutter SDK. The package requires AndroidX — if your project isn’t migrated, update it.

iOS: Keychain Error -34018

The dreaded -34018 error indicates a keychain permission problem. To fix it:

1. Open your project in Xcode.
2. Select your app target, go to Capabilities.
3. Turn on “Keychain Sharing”.
4. No need to add a specific group — just enabling it resolves the issue for most apps.

If you still see the error, check that your app’s bundle identifier matches the provisioning profile.

Encrypt Package: Wrong Key or Padding

The encrypt package provides AES encryption but has pitfalls. A common mistake is using a raw string as a key when it needs to be a 16, 24, or 32-byte key.

final key = Key.fromUtf8('my32lengthkey00000000000000000'); // Must be 32 bytes for AES-256
final iv = IV.fromLength(16);
final encrypter = Encrypter(AES(key));
final encrypted = encrypter.encrypt('plaintext', iv: iv);

Another issue: not passing an IV at all. AES-CBC requires a random IV; AES-GCM uses a nonce. Always provide one.

Plugin Not Registered on iOS

If your security plugin works on Android but not iOS, it’s likely a Swift/Objective-C bridging issue. Make sure your plugin is correctly imported:

• In ios/Runner/AppDelegate.swift, verify that FlutterPluginRegistrant.register(with: self) is called.
• If you used Flutter 3.0+, check your ios/Podfile for platform version — it should be at least 11.0.

Android: Cleartext HTTP Traffic Error

Some security plugins try to load assets via HTTP. If you see a cleartext HTTP error, add an Android network security config. Create android/app/src/main/res/xml/network_security_config.xml:

<network-security-config>
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
    </domain-config>
</network-security-config>

Then reference it in the Android manifest inside <application>:

android:networkSecurityConfig="@xml/network_security_config"

Comparing Flutter Security Plugins

Plugin	Common Failure	Solution
flutter_secure_storage	Keychain error -34018	Enable Keychain Sharing in Xcode
flutter_secure_storage	Android Null/Error	Set minSdkVersion to 18
encrypt	Bad key length	Use 16/24/32 byte key for AES
local_auth	Biometrics not available	Check device support and permissions
pointycastle	Algorithm not found	Import correct provider and register

Debugging Security Plugin Registration

When a plugin simply doesn’t respond, it’s often a registration issue. Here’s a step-by-step approach:

1. Run flutter clean and flutter pub get to refresh dependencies.
2. Ensure the plugin is in your pubspec.yaml under dependencies (not dev_dependencies).
3. On iOS, delete ios/Podfile.lock and run pod install again.
4. Check the runner’s AppDelegate — some plugins need manual registration in older Flutter versions.
5. Use flutter logs to see device logs. Look for lines containing the plugin name.

Preventing Common Mistakes with API Keys and Certificates

Security plugins often manage API keys or certificate pins. A frequent error is misconfiguring certificate pinning (see our guide on Certificate Pinning: What It Is and When to Use It). If your HTTP client throws a handshake error, the pin might be wrong or the certificate has rotated.

Similarly, when handling API keys in mobile apps, many developers hardcode them despite using a storage plugin. That defeats the purpose. Read Handling API Keys in Mobile Apps Safely for a better approach.

When All Else Fails: Reset and Test

Sometimes the quickest fix is to clear all stored data:

• On Android: Go to Settings > Apps > Your App > Storage > Clear Data.
• On iOS: Delete and reinstall the app from the device.
• In code: Call deleteAll() on flutter_secure_storage to reset the keychain.

Also run flutter run --verbose — it prints full error stacks that often reveal the missing step.

Don’t forget to check that your plugin versions are compatible. A mismatch between flutter_secure_storage 5.x and older Android Gradle plugins can cause build failures. Update everything to the latest stable release.

Platform-Specific Build Configurations

Sometimes the issue is not in the code but in the build configuration. On iOS, check your Info.plist for keys that affect security plugins. For example, NSFaceIDUsageDescription is required if you use biometric authentication. Without it, local_auth will fail on devices with Face ID. Add a description like:

<key>NSFaceIDUsageDescription</key>
<string>We need Face ID to unlock your data.</string>

On Android, ensure your build.gradle sets compileSdkVersion to 31 or higher for secure storage plugins that rely on Android 12’s encryption APIs. Also verify that targetSdkVersion is not too low — some plugins drop support for older SDKs.

Testing Security Plugins on Emulators vs Physical Devices

Many security features don’t work on emulators. For example, the iOS keychain behaves differently on a simulator: it stores data but may not enforce the same access control. If you’re only testing on emulators, you might miss keychain errors that appear on real devices. Similarly, Android’s EncryptedSharedPreferences might work fine on an emulator with debug build but crash on a release APK due to missing ProGuard rules.

To avoid surprises, always test on a physical device with a release build before shipping. Add ProGuard rules for security plugins in android/app/proguard-rules.pro:

-keep class com.it_nomads.fluttersecurestorage.** { *; }
-keep class net.sqlcipher.** { *; }

These rules prevent the obfuscator from stripping plugin classes.

Security is hard, but plugin issues don’t have to be. Start with platform configuration, then verify encryption parameters. Most errors boil down to those two areas.

Frequently asked questions

Why does flutter_secure_storage return null on Android?

This usually happens when the minimum SDK version is below 18. Set minSdkVersion to 18 in android/app/build.gradle. Also check that you’re using AndroidX and the plugin is compatible with your Flutter version.

How do I fix Keychain error -34018 on iOS?

Enable Keychain Sharing in Xcode: go to your target’s Capabilities and toggle on Keychain Sharing. You don’t need to add a group. This resolves most -34018 errors.

What is the correct key size for AES encryption in the encrypt package?

AES supports key sizes of 16, 24, or 32 bytes. Use a 32-byte key for AES-256. Convert your string to bytes with Key.fromUtf8() and ensure the length is correct.

Why is my Flutter security plugin not registering on iOS?

Check that FlutterPluginRegistrant.register(with: self) is called in AppDelegate.swift. Also update your Podfile platform to iOS 11.0 or later. Run pod install after changes.

How can I clear all data stored by flutter_secure_storage during testing?

Call deleteAll() from the plugin to clear all keychain items. Alternatively, delete the app from the device and reinstall. On Android, you can also clear app data from Settings.