Flutter: Failed to lookup symbol 'mmkvInitialize': dlsym(RTLD_DEFAULT, mmkvInitialize): symbol not found

[blackstorm]

The language of MMKV

Dart / FFI (via mmkv_ios Flutter plugin, wrapping the native MMKV library written in Objective‑C++ / C++)

The version of MMKV

v2.4.1 (latest, released 2026-07-30) — runtime regression; v2.4.0 works when installed via CocoaPods.

The platform of MMKV

iOS (Xcode 26.0, iPhoneOS 26.0 SDK, arm64, physical device only; simulator builds work without this issue)

The installation of MMKV

• Swift Package Manager (SPM) – integrated via the Flutter plugin mmkv / mmkv_ios (pubspec dependency).
• The native library is declared in the Xcode project through SPM (Package.resolved).
• Not using CocoaPods for this setup. For comparison, v2.4.0 via CocoaPods works on both simulators and devices.

What's the issue?

On physical iOS devices, the app crashes immediately after launch when MMKV.initialize() is called. The Dart FFI layer fails to look up the symbol mmkvInitialize:

ArgumentError: Invalid argument(s): Failed to lookup symbol 'mmkvInitialize': dlsym(RTLD_DEFAULT, mmkvInitialize): symbol not found

The root cause: the native MMKV framework is not bundled into the final .app for device builds. Inspecting the app package reveals that MMKV.framework is missing from the Frameworks folder.

• The build succeeds with no compile errors.
• The crash occurs only on physical devices; simulator builds run fine because the library might be linked differently or the simulator uses a different path.
• The same project built with v2.4.0 via CocoaPods includes the framework correctly on both simulators and devices.

What's the log of MMKV when that happened?

No MMKV log is produced because the library is never loaded.

Full error stack trace (sanitized):

[ERROR:flutter/runtime/dart_vm_initializer.cc(41)] Unhandled Exception: ArgumentError: Invalid argument(s): Failed to lookup symbol 'mmkvInitialize': dlsym(RTLD_DEFAULT, mmkvInitialize): symbol not found
#0      DynamicLibrary.lookup (dart:ffi-patch/ffi_dynamic_library_patch.dart:33)
#1      MMKVPlatformIOS._mmkvInitialize (package:mmkv_ios/mmkv_ios.dart:48)
#2      MMKVPlatformIOS.initialize (package:mmkv_ios/mmkv_ios.dart:54)
#3      MMKV.initialize (package:mmkv/mmkv.dart:228)
#4      warmUpPlatformAndStorage (package:your_app/app/run_app.dart:106)
#5      bootstrapAndRun (package:your_app/app/run_app.dart:45)
...

The main thread (thread 0) crashes with this exception; other threads (raster, I/O, workers) are idle.

Environment details (additional context)

• Xcode: 26.0 (Build 17A400)
• iOS SDK: 26.0 (iphoneos26.0)
• Flutter: version 3.12.2 (using mmkv plugin, latest)
• Deployment target: iOS 15+ (tested on iOS 26.6 and 18.7.8 physical devices)

Version comparison

The following observations have been made across different installation methods and MMKV versions:

Installation Method	MMKV Version	Result
CocoaPods	2.4.0	Builds successfully, works correctly on both simulator and physical devices.
SPM	2.4.1	Builds without compile errors. However, it crashes at runtime on physical devices due to the missing symbol mmkvInitialize. On simulators, the same SPM setup works fine.

Additional observations

• The missing framework on device builds indicates that the SPM package definition for v2.4.1 does not correctly handle embedding for physical architectures (arm64).
• Simulator builds may use a different linking strategy (e.g., dynamic linking from the build directory), which hides the problem.
• This is a regression from v2.4.0, where CocoaPods correctly embedded the library for all targets.

[github-actions]

👋 Hello! Thanks for opening an issue.

Note

New features, bugfixes, updates and other improvements are all handled mostly by @lingol in his free time.
To support @lingol , please consider 💖 sponsoring him on GitHub 💖.
Sponsored issues will be prioritized.

(If you are already a sponsor, thank you! We will get to this shortly.)

[lingol]

You should provide details information as the issue template required. @blackstorm

[lingol]

Especially, the platform you were building (iOS, Android, etc). The Flutter version. etc.

[lingol]

Or you can prove a reproduce demo project.

[blackstorm]

@lingol updated

[lingol]

This does not look like a missing-framework embedding issue. With Flutter’s SwiftPM integration, the plugin is linked statically, so it is normal that MMKV.framework is not present in Runner.app/Frameworks.

The actual problem is that the Dart FFI APIs, including mmkvInitialize, are found through:

DynamicLibrary.process().lookup("mmkvInitialize")

Because this is only a string lookup, the native linker does not see a reference to mmkvInitialize and may omit flutter-bridge.o from the final app. All MMKV Flutter C APIs are defined in that same object file, so forcing one symbol to be linked should bring in all of them.

As a temporary workaround, without modifying the Xcode workspace or MMKV itself, add the following line to both:

• ios/Flutter/Debug.xcconfig
• ios/Flutter/Release.xcconfig

OTHER_LDFLAGS = $(inherited) -Wl,-u,_mmkvInitialize

Do not add it to Generated.xcconfig, because Flutter regenerates that file.

Then rebuild cleanly:

flutter clean
flutter pub get
flutter run

The leading underscore in _mmkvInitialize is required because that is the Mach-O linker symbol name.

You can verify the fix with:

nm -gU build/ios/iphoneos/Runner.app/Runner | grep _mmkvInitialize

Depending on the Xcode Debug build layout, the symbol may instead be in:

nm -gU build/ios/iphoneos/Runner.app/Runner.debug.dylib | grep _mmkvInitialize

If this workaround fixes the crash, it confirms that the issue is static archive member selection, not framework embedding.

[lingol]

@blackstorm Any updates on this issue?

[lingol]

I have fixed it in dev branch, you can test it by using it:

1. create an pubspec_overrides.yaml in your flutter project
   your_flutter_app/
   ├── android/
   ├── ios/
   ├── lib/
   ├── pubspec.yaml
   └── pubspec_overrides.yaml ← create this file here

2. Put this inside pubspec_overrides.yaml:

  dependency_overrides:
    mmkv_ios:
      git:
        url: https://github.com/Tencent/MMKV.git
        ref: dev
        path: flutter/mmkv_ios

3. Then, from your_flutter_app/, run:

  flutter clean
  flutter pub get
  flutter run --release

[blackstorm]

Hi @lingol

Thanks for the dev-branch fix. I tested it per your instructions, and while it does solve the linking problem, I found that it does NOT survive the archive (flutter build ipa) path used for TestFlight/App Store distribution. On physical devices the app still crashes with the same dlsym error. Details below.

Environment

• Xcode 26.0, Flutter 3.12.x, iOS SDK 26.0, physical device
• mmkv_ios from dev branch via dependency_overrides (git, resolved-ref: bd7c8e6)

What I verified

1. The anchor fix works for linking

With the dev branch, _mmkvInitialize IS present in the final binary (confirmed via dSYM: external symbol in __TEXT,__text). The dead-strip extraction problem from #1676 is indeed fixed.

2. But the symbol is stripped from the export trie by the archive build

• flutter build ios --release (no archive): export trie contains mmkvInitialize → works
• flutter build ipa (archive): the Runner binary's export trie is reduced from ~8500 symbols to just 2 stubs (__mh_execute_header, piecewise_construct). mmkvInitialize is gone.

The archive log shows the cause:
/usr/bin/strip -D .../Runner.app/Runner (in target 'Runner')

Since Dart FFI resolves via dlsym(RTLD_DEFAULT, "mmkvInitialize"), which only searches each image's export trie, the stripped binary fails at runtime on device — same symbol not found crash as before.

3. Control experiments

On a minimal test binary with -Wl,-exported_symbol,_myExportedFunc:

strip mode	symbol survives in export trie?
strip -x	yes
strip (default)	no
strip -D (what archive uses)	no

So even forcing the export at link time does not protect against the archive strip.

Happy to help test once you have an updated branch. Note: I tested with flutter build ipa — flutter run --release won't reproduce this, which is probably why it passed on your side.

[lingol]

That's strange. Why don't you provide a demo project that reproduces the problem? It's faster this way.

[lingol]

I'm afraid there's noting we can do about it without a demo project. Here're some more ways you can test on your side. @blackstorm

Option 1: Preserve external symbols in Runner

In Xcode, select:

Runner target
→ Build Settings
→ Strip Style
→ Release
→ Non-Global Symbols

Equivalent setting:

  STRIP_STYLE = non-global

Then rebuild:

  flutter clean
  flutter build ipa --release

This makes Xcode use strip -x, which preserves external symbols such as
mmkvInitialize.

Option 2: Build the FFI bridge dynamically

A cleaner package-level approach is to put the FFI exports in a dynamic library
instead of the Runner executable.

In flutter/mmkv_ios/darwin/mmkv_ios/Package.swift, change:

  .library(name: "mmkv-ios", targets: ["mmkv_ios"])

to:

  .library(
      name: "mmkv-ios",
      type: .dynamic,
      targets: ["mmkv_ios"]
  )

Then rebuild:

  flutter clean
  flutter pub get
  flutter build ipa --release

Please test the resulting IPA on a physical device. The dynamic approach should
preserve the FFI exports in the library’s export trie even when Xcode strips
Runner.

Changing only MMKVCore to dynamic would not be sufficient because the Dart FFI
entry points, including mmkvInitialize, are implemented in the outer mmkv_ios
target.

[blackstorm]

@lingol I'll share a minimal repro project later.

[lingol]

@blackstorm We are waiting.