Skip to main content

Troubleshooting

Download stuck in "pending" state (Android)

This can happen with slow-responding servers. The library automatically adds keep-alive headers, but you can also try:

  • Increase timeout by setting custom headers
  • Check if the server supports the download URL
  • Enable debug logs to see what's happening: setConfig({ isLogsEnabled: true })
Duplicate class errors with react-native-mmkv (Android)

If you're using react-native-mmkv, you don't need to add the MMKV dependency manually - it's already included. The library uses compileOnly to avoid conflicts.

react-native-mmkv v4.x uses Margelo's fork of MMKV (io.github.zhongwuzw:mmkv) which re-adds armeabi-v7a (32-bit ARM) support, so you have full ABI coverage including 32-bit devices when using react-native-mmkv.

EXC_BAD_ACCESS crash on iOS with react-native-mmkv

This was fixed in v4.4.0. Update to the latest version. The podspec declares the MMKV dependency itself, so you don't need to add anything to your Podfile. If you do pin it manually, exclude the broken 2.4.1 release (see the entry below):

pod 'MMKV', '>= 1.0.0', '!= 2.4.1'
iOS build fails with "use of undeclared identifier 'memset_s'" (MMKVCore)
Pods/MMKVCore/Core/aes/AESCrypt.cpp:83:11
(void)memset_s(ptr, len, 0, len);
      ^ use of undeclared identifier 'memset_s'

This is an upstream bug in MMKVCore 2.4.1 (Tencent/MMKV#1675) - it does not compile on Apple platforms. Update to the latest version of this library: the podspec now excludes exactly that release, so a fresh pod install resolves MMKVCore 2.4.0 instead.

If you are on a version with the fix and still hitting this, your Podfile.lock is pinning the broken version. Refresh it:

cd ios
pod update MMKV MMKVCore

If some other pod in your graph forces MMKVCore 2.4.1 and you cannot move off it, define the missing feature-test macro on the command line (the #define inside AESCrypt.cpp lands too late because CocoaPods force-includes the generated prefix header first):

# ios/Podfile
post_install do |installer|
  installer.pods_project.targets.each do |target|
    next unless target.name == 'MMKVCore'
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << '__STDC_WANT_LIB_EXT1__=1'
    end
  end
end
Downloads "don't work" when the iOS screen is locked

On iOS the actual transfer is handed to the system nsurlsessiond daemon and keeps running while the app is suspended and the screen is locked - this library already configures the background session correctly (discretionary = NO, sessionSendsLaunchEvents = YES). If it looks like downloads stop when locked, check these in order:

  1. Did you force-quit the app? If the user swipes the app away in the app switcher, iOS halts that app's background transfers until it's relaunched. This is an OS policy and cannot be worked around by any library.
  2. You won't get live progress events while locked. Your JavaScript isn't running while the app is suspended, so begin / progress / complete callbacks fire when the app resumes or is relaunched - not in real time. Re-attach with getExistingDownloadTasks() on launch.
  3. AppDelegate wiring. Make sure handleEventsForBackgroundURLSession is implemented (see Installation) and that you call completeHandler(jobId) from JS in your complete/error handlers, or iOS will throttle future background time.
  4. Data Protection (the one this library handles). On a passcoded, locked device, files protected with NSFileProtectionComplete can't be written, so a download that finishes while locked could previously fail to save. The library now writes the file with NSFileProtectionCompleteUntilFirstUserAuthentication by default (writable while locked after the first unlock since boot), and if the move still can't happen because the device is locked it stages the bytes and completes the save automatically when the device is next unlocked - emitting complete then. You can change the level with setConfig({ iosDataProtection }) or per task (see Advanced Configuration).
  5. Test on a real device. The iOS Simulator's background-transfer behavior is unreliable; verify on hardware.
Downloads not resuming after app restart

Make sure to call getExistingDownloadTasks() at app startup and re-attach your callbacks. The task IDs you provide are used to identify downloads across restarts.

Google Play Console asking about Foreground Service

See the Google Play Console Declaration section for the required steps.

TypeToken errors in release builds (Android)

Add the Proguard rules mentioned in the Proguard Rules section.