Diagnosing Native Module Linking Failures in React Native

The Problem: "Native Module is Null"

A common failure in React Native development occurs when a JavaScript library is installed via npm or yarn, but the application crashes or returns null when attempting to call a native method. This happens because the JavaScript bridge cannot find the corresponding native implementation in the compiled binary.

The primary takeaway is that installation is not integration. While npm install adds the JS code, the native build systems (Gradle for Android, CocoaPods for iOS) must explicitly link the binary code into the app package.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Check
Build fails in Xcode/Android Studio	Missing dependency declaration	Podfile / build.gradle
App crashes on startup (iOS)	Missing Framework/Binary	Link Binary With Libraries
undefined is not an object at runtime	Auto-linking failure	react-native.config.js
Works on simulator, fails on device	Architecture mismatch	Excluded Architectures (Xcode)

Step-by-Step Verification Sequence

Follow these checks in order to isolate whether the failure is at the package level, the build configuration level, or the binary level.

1. Package Integrity Check

Verify that the module is physically present in the node_modules directory and recognized by the CLI.

• Run npx react-native info on your terminal.
• Check the "Installed libraries" section. If the module is missing, run npm install or yarn install.
• Ensure the module is listed under dependencies in package.json, not just devDependencies, as some build pipelines ignore the latter.

2. Auto-linking Validation

Modern React Native versions use auto-linking to avoid manual edits to native files. However, custom configurations can disable this.

• Check for a react-native.config.js file in the root directory.
• Ensure the module isn't explicitly disabled under the dependencies key (e.g., "module-name": { "platforms": { "ios": null } }).

3. iOS Integration Check

On iOS, the Podfile acts as the source of truth for native dependencies.

1. Navigate to the iOS directory: cd ios.
2. Run pod install. Watch for errors indicating the pod cannot be found.
3. Open .xcworkspace in Xcode. Navigate to Build Phases > Link Binary With Libraries. Ensure the module's .framework or .a file is listed.

4. Android Integration Check

Android relies on Gradle to pull in .aar or .jar files.

1. Open android/app/build.gradle.
2. Verify the dependencies block contains the implementation line for the module if auto-linking failed.
3. Run ./gradlew clean from the android folder to remove stale build artifacts that might be referencing an old version of the library.

Fixing Common Linking Failures

Scenario A: Stale Build Artifacts

If you updated a library version but the app still behaves as if the old version (or no version) is installed, clear the caches.

# iOS Clean
cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update && cd ..

# Android Clean
cd android && ./gradlew clean && cd ..

Scenario B: Architecture Mismatch (iOS)

If the app crashes only on a physical device (arm64) but works on a simulator (x86_64), the native library may be missing a slice for the target architecture.

• In Xcode, go to Build Settings.
• Search for Excluded Architectures.
• Ensure arm64 is not accidentally excluded for the "Any iOS SDK" setting.

Scenario C: Manual Linking Conflict

If you see "Duplicate Symbol" errors, you likely have both auto-linking and manual linking active.

• Remove manual import statements in MainApplication.java (Android) or manual framework additions in Xcode.
• Rely solely on the auto-linking mechanism provided by the React Native CLI.

Verification and Escalation

To verify the fix, rebuild the app entirely: npx react-native run-ios or npx react-native run-android. If the module still returns null, check the following escalation criteria:

• Version Mismatch: Compare the React Native version in package.json with the module's supported versions in its README.
• Missing Permissions: Check if the module requires Info.plist (iOS) or AndroidManifest.xml (Android) entries (e.g., Camera, Location). Missing permissions can sometimes cause the native module to fail initialization silently.
• Native Entry Point: If this is a custom-built module, verify that the native class is correctly registered with the ReactPackage interface.