{
  "id": "android/unsatisfiedlinkerror-native-library-not-loaded",
  "signature": "java.lang.UnsatisfiedLinkError: dlopen failed: library \"libnative.so\" not found",
  "signature_zh": "java.lang.UnsatisfiedLinkError: dlopen 失败：找不到库 \"libnative.so\"",
  "regex": "java\\.lang\\.UnsatisfiedLinkError: dlopen failed: library \"[^\"]+\" not found",
  "domain": "android",
  "category": "runtime_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "原生库 (.so) 缺少、未打包到对应设备 ABI 的 APK 中，或因路径错误或二进制文件损坏导致加载失败。",
  "versions": [
    {
      "version": "Android 11 (API 30)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Android 12 (API 31)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Android 13 (API 33)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Android 14 (API 34)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The .so file is not automatically included in the APK unless the jniLibs source set is properly configured.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Modern Gradle requires the jniLibs directory or ABI splits; direct file references for native libs are not supported.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This flag prevents extracting native libs from the APK, but if the lib is already missing for the target ABI, it won't help.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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']",
      "success_rate": 0.9,
      "how": "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']",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use Gradle ABI filters: android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' to include only supported architectures.",
      "success_rate": 0.85,
      "how": "Use Gradle ABI filters: android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' to include only supported architectures.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.95,
      "how": "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.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "将 .so 文件放入 app/src/main/jniLibs/<abi>/ 目录（例如 arm64-v8a），并在 build.gradle 中添加：sourceSets.main.jniLibs.srcDirs = ['src/main/jniLibs']",
    "使用 Gradle ABI 过滤器：android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' 以仅包含支持的架构。",
    "如果是第三方 SDK，使用 SDK 提供的集成方式（如 Maven 或 AAR）重新添加依赖，而不是手动放置 .so 文件。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://developer.android.com/ndk/guides/abis",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-03-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}