Troubleshooting

Common build and runtime errors, and what they usually mean.

iOS: missing MMKV dependency

Undefined symbol: _OBJC_CLASS_$_MMKV

Your iOS app links the Documents framework but hasn't declared MMKV itself as a dependency of the app target. Documents depends on MMKV, but embedding the Documents framework doesn't automatically pull MMKV's native binary along with it — your app needs to add MMKV directly, via CocoaPods or Swift Package Manager, the same way it adds any other native dependency. See MMKV's own iOS setup guide for both paths.

Crash on the first update() call: DocumentDecodingException

DocumentDecodingException: Failed to decode field 'title' of document 'note'

This is the single most common first-run surprise with this library, and it usually has nothing to do with corrupted data. It fires when update() runs against a document that has never been set(), and at least one field in your @Serializable data class is both non-nullable and has no constructor default — for example data class Note(val title: String, val count: Int). With nothing stored yet and no default to fall back to, the library has no value to seed that field with, so it throws instead of guessing.

The message is generic today — it reads exactly like a genuinely corrupted field would (see Error Handling) — so it's easy to mistake for a data integrity bug rather than a missing default. A clearer, dedicated message for this specific case is planned.

Fix it by giving every field either a constructor default or a nullable type:

data class Note(val title: String = "", val count: Int = 0)

See Declaring Data Classes for the full rule and more examples.