android runtime_error ai_generated true

java.lang.UnsatisfiedLinkError: dlopen failed: library "libnative.so" not found

ID: android/unsatisfiedlinkerror-native-library-not-loaded

Also available as: JSON · Markdown · 中文
85%Fix Rate
88%Confidence
1Evidence
2023-03-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Android 11 (API 30) active — — —
Android 12 (API 31) active — — —
Android 13 (API 33) active — — —
Android 14 (API 34) active — — —

Root Cause

A native library (.so) is missing from the APK, not packaged for the device's ABI, or fails to load due to incorrect path or corrupted binary.

generic

中文

原生库 (.so) 缺少、未打包到对应设备 ABI 的 APK 中，或因路径错误或二进制文件损坏导致加载失败。

Official Documentation

https://developer.android.com/ndk/guides/abis

Workarounds

  1. 90% success Place the .so file in app/src/main/jniLibs/<abi>/ (e.g., arm64-v8a) and ensure build.gradle includes: sourceSets.main.jniLibs.srcDirs = ['src/main/jniLibs'] 
    Place the .so file in app/src/main/jniLibs/<abi>/ (e.g., arm64-v8a) and ensure build.gradle includes: sourceSets.main.jniLibs.srcDirs = ['src/main/jniLibs']
  2. 85% success Use Gradle ABI filters: android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' to include only supported architectures. 
    Use Gradle ABI filters: android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' to include only supported architectures.
  3. 95% success If using a third-party SDK, re-add the dependency via the SDK's provided integration method (e.g., Maven or AAR) instead of manual .so file placement. 
    If using a third-party SDK, re-add the dependency via the SDK's provided integration method (e.g., Maven or AAR) instead of manual .so file placement.

中文步骤

  1. 将 .so 文件放入 app/src/main/jniLibs/<abi>/ 目录（例如 arm64-v8a），并在 build.gradle 中添加：sourceSets.main.jniLibs.srcDirs = ['src/main/jniLibs']
  2. 使用 Gradle ABI 过滤器：android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' 以仅包含支持的架构。
  3. 如果是第三方 SDK，使用 SDK 提供的集成方式（如 Maven 或 AAR）重新添加依赖，而不是手动放置 .so 文件。

Dead Ends

Common approaches that don't work:

  1. 70% fail

    The .so file is not automatically included in the APK unless the jniLibs source set is properly configured.

  2. 60% fail

    Modern Gradle requires the jniLibs directory or ABI splits; direct file references for native libs are not supported.

  3. 50% fail

    This flag prevents extracting native libs from the APK, but if the lib is already missing for the target ABI, it won't help.