Troubleshooting

Troubleshooting

UnsupportedOperationException from the secure store (Android)

SecureDatastore requires Android API 23 (Marshmallow)+. Older devices throw this from the secure API only — the regular NativeDatastore still works. Gate secure usage or raise your minSdkVersion.

Reads return null unexpectedly

• The key was never written, or was written under a different type. Getters are strict — a value written with setInt won't come back from getString.
• For the secure store, getString returns null if the key was last written with setBytes (and vice-versa) — they're separate buckets.

Values not shared with my background service / extension

You need Multi-Process Access: call configure(...) before the first read/write, and remember the Android multi-process store uses a separate file (existing default-store values aren't visible through it).

iOS: secrets not shared across the app and its extension

SecureDatastore cross-process sharing uses a Keychain access group, set via configure(appGroupId: '<access-group>'), and requires the Keychain Sharing capability in Xcode. Note the access-group string is not the same as the App Group suite the regular store uses.

Lost writes / CorruptionException / "old" values after upgrade

Classic signs of using the default single-process store from multiple processes. Either keep all access in the main process, or opt into Multi-Process Access.

DateTime comes back in UTC

By design — values are stored and returned in UTC. Call .toLocal() if you need local time.

Build error: Package name must be a '.'-separated identifier list (Android)

The Pigeon-generated Kotlin didn't escape the reserved in keyword in the package name. Regenerate bindings with tool/generate_pigeon.sh (not dart run pigeon directly), which applies the escape automatically.

Still stuck?

• Check the FAQ in the README.
• Open an issue with your flutter doctor -v, plugin version, platform, and a minimal repro.