Debugging React Native Native Bridge Module Errors

The first ten minutes — establish facts before touching code.

• 1Run the app and capture native logs immediately: on iOS use `npx react-native log-ios`; on Android use `npx react-native log-android` or `adb logcat | grep -i reactnative`.
• 2Check if the module is registered in JS by logging `console.log(NativeModules)` in your app and looking for your module name.
• 3Verify the module is listed in the bundle: on iOS, search for 'YourModule' in the Xcode build logs (Cmd+9, search step output). On Android, check the Build Output window for 'YourModule'.
• 4For iOS, run `nm -u <path-to-app-binary> | grep YourModule` to see if the symbol is undefined (missing link).
• 5For Android, use `gradlew :app:dependencies` to ensure the module's library is included.
• 6If using TurboModules, check that the codegen step ran: look for generated files in `android/app/build/generated/source/codegen`.

The specific files, logs, configs, and dashboards that usually own this bug.

• searchiOS: AppDelegate.m or AppDelegate.swift — check if the module's header is imported and if it's registered in the bridge (e.g., [RCTBridge initWithDelegate:...] or [module registerBridge:...]).
• searchiOS: Podfile and Podfile.lock — ensure the module's pod is correctly specified and linked (e.g., `pod 'YourModule', :path => '../node_modules/your-module'`).
• searchAndroid: MainApplication.java — look in the getPackages() method for your module's package instance.
• searchAndroid: AndroidManifest.xml — check for any required activities or permissions the module expects.
• searchJavaScript: index.js or the module's JS entry point — ensure NativeModules is imported correctly and the module name matches.
• searchBuild logs: Xcode build log (iOS) or Gradle console output (Android) — search for errors like 'Undefined symbols' or 'package not found'.
• searchReact Native DevTools console or Chrome debugger — the error stack trace often points to the exact line in JS where the native call failed.

Practical causes, not theory. These are the things you will actually find.

• warningiOS: Missing #import of the module's header in AppDelegate and not registering it with the bridge.
• warningiOS: Swift module missing @objc annotation or not exposed to Objective-C via bridging header.
• warningiOS: Module's .m file missing RCT_EXPORT_MODULE() macro.
• warningAndroid: Module class missing @ReactMethod annotation on exposed methods.
• warningAndroid: Package class not added to getPackages() list in MainApplication.java.
• warningBoth platforms: Module's native library not linked (e.g., missing pod install or gradle sync).
• warningNew Architecture: TurboModule JS spec not generated or JS calling old NativeModules API.
• warningMisnamed module: JS expects 'MyModule' but native exports 'MYModule' (case-sensitive).

Concrete fix directions. Pick the one that matches your root cause.

• buildOn iOS, add `#import "YourModule.h"` at the top of AppDelegate.m and register it with `[self.bridge registerModule:YourModule.class]` or ensure it's auto-registered via RCT_EXPORT_MODULE.
• buildFor Swift modules, make sure the class inherits from RCTEventEmitter or NSObject and uses @objc, and add `#import "<ProjectName>-Swift.h"` in AppDelegate.
• buildOn Android, implement the package class that extends ReactPackage and override createNativeModules to return your module instance, then add it to getPackages().
• buildRun `cd ios && pod install` after adding a new native module pod. For Android, run `./gradlew clean` and rebuild.
• buildFor TurboModules, run `npx react-native codegen` to generate the native interface, then use `requireNativeComponent` or `TurboModuleRegistry.get` with the correct spec name.
• buildCheck case sensitivity: NativeModules.YourModule must match the name in RCT_EXPORT_MODULE() or ReactMethod name exactly. Use lowercase for the first letter of the module name? Actually, React Native expects PascalCase for module names in JS. Be consistent.
• buildIf the module is a third-party library, ensure it's installed correctly: `npm install` and then `react-native link` (for RN < 0.60) or auto-link (for RN >= 0.60) should handle it, but sometimes manual linking is needed.

A fix you cannot prove is a guess. Close the loop.

• verifiedAfter fix, run the app and check native logs: you should see a line like 'RCTBridge registered module YourModule' on iOS or 'ReactNative: Registering native module: YourModule' on Android.
• verifiedIn JS, call `console.log(NativeModules.YourModule)` and confirm it's an object with your methods.
• verifiedCall a simple method (e.g., `NativeModules.YourModule.ping()` that returns a string) and verify the response.
• verifiedIf using TurboModules, check that `TurboModuleRegistry.get('YourModule')` returns a non-null object.
• verifiedRun the app on both simulators/emulators and physical devices to rule out device-specific issues.
• verifiedWrite a unit test that imports the module and invokes a method to ensure the bridge is working in a test environment.

Things that make this bug worse or harder to find.

• warningDon't forget to rebuild the native app after changes: `npx react-native run-ios` or `run-android` does this, but if you modify native code, you need to rebuild the native project from Xcode/Android Studio.
• warningAvoid using the same module name for different platforms that conflict (e.g., both have 'MyModule' but different case).
• warningDon't assume auto-linking works for custom modules inside a monorepo; you may need to add the module path to the Podfile or settings.gradle.
• warningNever ignore warnings during pod install or gradle build — they often indicate missing dependencies that will cause runtime failures.
• warningDon't use the old `react-native link` command for React Native 0.60+; it can break auto-linking.
• warningAvoid relying on the Chrome debugger for native bridge issues; the debugger can mask the error because it runs JS in a different context. Use Flipper or native logs instead.

Frequently asked questions