Diagnosing and Fixing React Native Native‑Module Linking Failures

The Problem: A Native Module Crash on Startup

After adding a native‑code dependency, the app may crash immediately or show a red screen with messages such as Native module cannot be null, Unable to resolve module, or dlopen failed: library not found. The root cause is usually a mismatch between the JavaScript bundle and the compiled native binaries.

Symptom Matrix

Symptom	Common Cause	Primary Check
App crashes immediately after launch (iOS)	Missing or outdated CocoaPods dependency	Verify Podfile.lock for the module
Android logcat shows dlopen failed: library not found	Gradle did not include the native library	Check app/build.gradle for the module dependency
Red screen with Unable to resolve module	Metro cache still references an old bundle	Restart Metro with --reset-cache
JavaScript reports NativeModules.ModuleName === undefined	Autolinking did not register the module	Inspect react-native.config.js and native project files

Ordered Checks

1. Check Compatibility

   Run npm list react-native to see the current RN version. Compare it with the module’s peerDependencies in its package.json or README. If they differ, install a compatible module version: npm install module-name@x.y.z.

2. Synchronize Native Dependencies

   iOS: cd ios && pod install && cd .. (requires macOS, CocoaPods, network). Risk: No internet may leave Podfile.lock incomplete.

   Android: cd android && ./gradlew clean && cd .. (requires Gradle wrapper). Clean removes stale build artifacts that might reference an old library.

3. Reset Metro Cache

   Run npx react-native start --reset-cache from the project root. If Watchman is installed, watchman watch-del-all clears its state.

4. Verify Autolinking

   Open react-native.config.js if present. Ensure the module is listed under dependencies and that no platforms: { ios: null, android: null } entry disables autolinking.

5. Inspect Native Project Files

   iOS: In Xcode, confirm the module’s framework appears under Frameworks, Libraries, and Embedded Content.

   Android: In Android Studio, open app/build.gradle and confirm the module dependency is present and the compileSdkVersion matches the module’s requirement.

Fixes Tied to Findings

• Version Mismatch – Align the module and RN versions as described in step 1.
• Missing CocoaPods or Gradle Entry – Re‑run the platform install commands from step 2 and rebuild.
• Stale Metro Cache – Restart Metro with --reset-cache (step 3).
• Autolinking Disabled – Edit react-native.config.js or add the module to react-native link (deprecated but works for older RN).
• Native Build Errors – Fix missing symbols or linker flags in the native project files. If the module ships a prebuilt binary, ensure the correct architecture is selected.

Escalation Criteria

1. After completing all checks, if the app still crashes, create a minimal RN project (e.g., npx react-native init TestApp) and install only the problematic module. If it fails there, the issue is likely in the module’s native source.
2. Open an issue on the module’s GitHub repository with the exact error logs and steps taken.
3. As a temporary workaround, revert to the last known working module version using npm install module-name@previous and verify the app launches.

Verification Checklist

1. Launch the app on a device or emulator and confirm the main screen appears without a red error.
2. In Xcode or Android Studio, watch the build output for any linker or dlopen errors.
3. In the JS console, run console.log(NativeModules.ModuleName). It should print an object, not undefined.
4. Run npx react-native doctor to ensure the environment is healthy.

Limitations and Practical Checks

• The guide assumes a native‑module‑enabled workflow. In an Expo managed project, custom native modules are not supported unless you eject to a bare workflow.
• Cache resets can temporarily increase build times; ensure a stable network for pod and Gradle downloads.
• Manual linking via react-native link is deprecated in RN 0.60+. Use it only if autolinking is unsupported by the module.