We’ve all been there.
You find an awesome library, you run npx expo install, you import it into your code, and you start your development server.
You expect magic.
Instead, your simulator turns blindingly red with an error that looks something like this:
ERROR Invariant Violation: TurboModuleRegistry.getEnforcing(...):
'RNGestureHandlerModule' could not be found.
Verify that your native modules are linked correctly.
Your app is completely bricked, your Metro bundler is acting confused, and you’re left wondering why a package you just installed is allegedly missing from the face of the earth.
Let's look at exactly why this happens and the 3-step checklist to clear it up without losing your sanity.
The Root Cause: JavaScript vs. Native Code
Modern Expo apps are beautifully split into two worlds:
The JS Bundle:
Your components, logic, and regular styles. Metro can hot-reload this in milliseconds.
The Native Layer:
The underlying Kotlin/Java and Swift/Objective-C code that actually talks to the phone's hardware.
When you install a package that uses native code (like react-native-gesture-handler, react-native-reanimated, or a map library), Metro cannot hot-reload native code into an active app binary.
If you are running a pre-built Development Client or using Expo Go, it only knows about the native modules that were compiled the last time you built the app.
It has no idea this new native module exists yet, so the registry panics and throws an Invariant Violation.
The Ultimate "Un-Brick My App" Checklist
Next time this red screen of death pops up, run through these three steps in order.
1. Rebuild the App Binary (The Absolute Must)
Simply restarting the Metro bundler won’t cut it.
You need to recompile your native code so the new library gets bundled into the actual simulator app.
Stop your server and run:
# For Android Simulators / Devices
npx expo run:android
# For iOS Simulators
npx expo run:ios
2. Force a Clean Prebuild (If Using Custom Native Directories)
If you are managing your own android or ios directories and things get desynced, force Expo to regenerate them with the new native dependencies linked:
npx expo prebuild --clean
This removes the generated native projects and recreates them from your Expo configuration, ensuring newly installed native packages are correctly integrated.
3. Nuke the Metro Cache
Sometimes Metro holds onto a stale dependency graph like a grudge.
If you’ve rebuilt the binary and it still complains, start your project while forcing a total cache clearance:
npx expo start -c
This clears Metro's cache and forces it to rebuild the dependency graph from scratch.
Final Thoughts
Native linking issues can feel incredibly frustrating because nothing appears wrong in your JavaScript code.
The problem is usually that your app binary and your JavaScript bundle have fallen out of sync.
Whenever you see errors like:
RNGestureHandlerModule could not be foundNative module cannot be nullTurboModuleRegistry.getEnforcing(...) failedModule has not been registered
Run through this checklist:
- Rebuild the app binary.
- Run a clean prebuild if you're using native directories.
- Clear the Metro cache.
Most of the time, one of those three steps will get you back up and running.
If you're reading this at 2:00 AM while violently copy-pasting cryptic mobile stack traces into search engines, I feel your pain deeply.
I got so tired of hunting down hidden Gradle errors and obscure CocoaPods issues that I decided to build a tool to automate the headache.
It's called Fix My Error.
I set up a completely registration-free sandbox right on the homepage using this exact native linkage error so you can see how it works in real time without handing over your data.
If you like how it parses the logs, you can drop your own daily errors into the core engine with a free account (which gives you 5 free fixes per day), or check out the Pro tier if you're working in a heavy production environment.
Give the sandbox a spin next time Expo decides to ruin your afternoon, and let me know if it helps your workflow.
How do you usually handle these types of native linking bugs?
Drop a comment if this checklist worked for you, or let me know if there's an obscure Expo error that's currently driving you crazy.
