📬 blog.addEventListener()? Sign me up | No, thanks

Resolving React Native version mismatch errors


There exists an especially difficult RedBox error you’ll encounter which reads: React Native version mismatch. JavaScript version: <x> Native version: <y>. This error occurs when the JavaScript and Native bits of your app get out of sync with one another. It’s critical that the RN developer tools call this out when it’s detected because a version discrepancy could lead to nasty issues if the app were allowed to run. In my experience, this error almost always shows up during or immediately following an upgrade of the core React Native package.

React Native app running on a simulator with the RedBox error showing 'React Native version mismatch'

The React Native upgrade process has received lots of attention over the past year, and as a result has seen huge improvements in how it works. I’ve written about it twice on this blog. First, a guide (which I still refer back to): Upgrading a React Native app with rn-diff-purge, and later a walk through of a real upgrade: React Native upgrade by example (featuring Purge Web). Having successfully completed a few upgrades and published posts on the subject, you may think that I have it figured out. You’d be incorrect. Occasionally I’ll get stuck for hours on an upgrade issue, and the React Native version mismatch is one that had me stumped for longer than I’d care to admit.

This tip is for those who’ve rebuilt, --reset-cache‘d, restarted, and begun pulling out their hair.

Cleaning the project

There is a super handy tool that is linked from the very bottom of the official RN upgrade docs called react-native-clean-project. This project can be used to clean out just about everything that can be cached and potentially be the cause of your version mismatch.

Install it as a dev dependency with the following command:

npm install --save-dev react-native-clean-project

Once installed, you can initiate a clean via the react-native CLI like so:

react-native clean-project-auto

The tool can be tweaked with a number of flags that are detailed in the README for additional cleaning steps, or to prevent some of the defaults.

After cleaning

Once your project is clean, you will need to reinstall your JS dependencies as well as any CocoaPods (if your project uses them):

npm install
pushd ios/
pod install
popd

With that, go ahead and run your app in debug mode on the simulator of your choice. On my current app, this involves opening Xcode and hitting the Play button.

And with that, the app is running and I’m back in business.

React Native SQLite demo app running on a simulator successfully

Thanks to Github user Pedro Madruga for this handy tool!