React Native New Architecture iOS Errors: 12 Common iOS Fixes
React Native uses the New Architecture by default since 0.76 and exclusively since 0.82. Most iOS errors come from Codegen, libraries and Hermes. 12 fixes.
Most React Native New Architecture iOS errors come from three places: Codegen and prebuilt binaries not being ready during pod install, third-party libraries that haven’t adopted the New Architecture, and packaging Hermes with the JS bundle. The New Architecture has been the default since 0.76 and the only option since 0.82, so the fix is to repair Codegen, update libraries and rerun pod install, not to turn it off. Below are 12 common problems as symptom, cause and fix. Version details follow the React Native blog and source code, as of October 2026.
Which New Architecture stage is your React Native version in?
The same error has different fixes on different versions. Look up the react-native version in package.json and compare it with this table.
| Version | Released | iOS-related changes |
|---|---|---|
| 0.76 | October 2024 | New Architecture on by default, can still be turned off with RCT_NEW_ARCH_ENABLED=0 |
| 0.81 | August 2025 | Last version that can use the old architecture. iOS builds need Xcode 16.1 or later |
| 0.82 | October 2025 | New Architecture only, the off switch is ignored. Old-architecture libraries keep working through the interop layer |
| 0.84 | February 2026 | Hermes V1 becomes the default engine. iOS uses prebuilt React Native binaries by default. Requires Node.js 22.11 or later |
| 0.87 | August 2026 | Experimental Swift Package Manager support on iOS |
| 0.88 | October 2026 | Current stable release. SceneDelegate support. CocoaPods still fully supported |
The 0.88 release notes say 0.89 plans to make Swift Package Manager the default, with CocoaPods removed later. This article covers the CocoaPods setup that’s still the mainstream today.
How do I match my iOS error to one of the 12 fixes?
| # | Symptom (excerpt) | Cause | Fix |
|---|---|---|---|
| 1 | pod install can’t find react_native_pods.rb |
JS dependencies aren’t installed | Run npm install in the project root first |
| 2 | required a higher minimum deployment target |
Deployment target is below what RN or a library requires | Use min_ios_version_supported, no lower than 15.1 |
| 3 | pod install fails or is slow downloading prebuilt binaries |
Network problem | Retry, or set RCT_USE_PREBUILT_RNCORE=0 to build from source |
| 4 | No such module 'ReactAppDependencyProvider', ReactCodegen headers not found |
Codegen output wasn’t generated or was deleted | Run pod install again |
| 5 | Still on the New Architecture after setting RCT_NEW_ARCH_ENABLED=0 |
Only the New Architecture is supported since 0.82 | Remove the switch and update incompatible libraries |
| 6 | TurboModuleRegistry.getEnforcing(...): 'Xxx' could not be found |
The native module isn’t in the app, or the library doesn’t support the New Architecture | Run pod install and rebuild, check the library’s compatibility |
| 7 | pod install says USE_HERMES=0 is no longer supported |
JSC moved out of core | Remove USE_HERMES=0, install the community package if you need JSC |
| 8 | Crash on launch with Wrong bytecode version in the log |
The hermesc that compiled the JS doesn’t match the Hermes in the app | Run pod install again after upgrading and clean old builds |
| 9 | Red screen Could not connect to development server |
The phone can’t reach Metro | Same local network, allow port 8081, allow Local Network |
| 10 | Release build shows a white screen or crashes on launch | The JS bundle isn’t in the app | Check the Bundle React Native code and images phase |
| 11 | Build or link errors after turning on use_frameworks! |
Static libraries mixed with dynamic frameworks | Use USE_FRAMEWORKS=static and follow each library’s docs |
| 12 | Many missing symbols and headers after an upgrade | Native template files weren’t upgraded | Compare with Upgrade Helper and run pod install again |
How do I fix errors during pod install?
1. react_native_pods.rb not found
The first part of the RN template’s Podfile uses node to look up react-native/scripts/react_native_pods.rb in node_modules. A freshly cloned project has no node_modules, so pod install fails right away, and the error mentions Cannot find module and that file name.
Install the JS dependencies in the project root first, then go into the ios folder.
1npm install
2cd ios
3pod install
2. Minimum deployment target too low
1[!] CocoaPods could not find compatible versions for pod "xxx":
2 ...
3Specs satisfying the `xxx` dependency were found, but they required a higher minimum deployment target.
In React Native 0.88’s CocoaPods scripts, min_ios_version_supported is 15.1. The template Podfile says platform :ios, min_ios_version_supported. Don’t replace it with a lower hard-coded version. When a library needs more, raise both the Podfile platform and the app target’s IPHONEOS_DEPLOYMENT_TARGET to what the library requires, then run pod install.
1platform :ios, '16.0' # when a library requires 16.0
3. Prebuilt binary download fails
Since 0.84, pod install downloads a prebuilt React Native .xcframework by default, which makes builds much faster. On a poor connection this step hangs or reports a download failure. Retry first. If it never completes, set an environment variable to build from source again, at the cost of a much longer first build.
1RCT_USE_PREBUILT_RNCORE=0 pod install
In PowerShell on Windows the syntax is different. Set the variable first, then run the command.
1$env:RCT_USE_PREBUILT_RNCORE = "0"
2pod install
With prebuilt binaries you can’t step into React Native’s internal native code. Breakpoints in your own native code work as usual.
4. Missing Codegen output
1No such module 'ReactAppDependencyProvider'
2'ReactCodegen/...h' file not found
The New Architecture uses Codegen to generate native glue code from the type declarations in your JS. It runs during pod install and writes its output to ios/build/generated/ios, and ReactCodegen and ReactAppDependencyProvider from that output are installed into the project as two local pods. After you delete ios/build, switch branches or add a library with native code, these files can be missing or stale.
Run pod install again in the ios folder. If your own Turbo Native Module doesn’t get generated code, check codegenConfig in package.json. jsSrcsDir must point to the folder with your spec files, module spec file names must start with Native, for example NativeLocalStorage.ts, and component specs must end with NativeComponent. See Using Codegen for the rules.
What if a library doesn’t support the New Architecture?
5. Can’t turn off the New Architecture
Since 0.82 there’s only the New Architecture. According to the official blog, running pod install with RCT_NEW_ARCH_ENABLED=0 on iOS is ignored. The script only prints a warning, and the app still runs on the New Architecture. For projects that still depend on the old architecture, the official advice is to stay on 0.81 or Expo SDK 54 until migration is done, then upgrade.
The switch no longer means anything, so remove it from the Podfile and CI scripts so it doesn’t mislead whoever comes next.
6. Native module not found, or a library isn’t compatible
1Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'RNXxx' could not be found.
2Verify that a module by this name is registered in the native binary.
There are two kinds of causes. Either the native part never made it into the app, because you installed the library without running pod install or didn’t rebuild afterwards. Or the library hasn’t adopted the New Architecture and the interop layer can’t handle how it’s used.
Rule out the first one. Run pod install in the ios folder, then do a full rebuild, not just a JS reload. If that doesn’t help, check the library’s compatibility in this order.
- Search for the library on reactnative.directory and see whether it’s marked as supporting the New Architecture.
- Check whether the library’s package.json has
codegenConfig. If it does, the author has adapted it for the New Architecture. - Look through the library’s GitHub issues for New Architecture problems and the versions that fixed them.
- Update to the latest version. For libraries that are no longer maintained, switch to an alternative marked as New Architecture compatible in the directory.
The 0.82 release notes say the interop layer will stay for the foreseeable future, and libraries that support both architectures keep working on New Architecture-only versions. The interop layer has known limits, such as no access to custom Shadow Nodes, so native components with custom layout are the most likely to break.
How do I fix Hermes errors on iOS?
7. USE_HERMES=0 is no longer supported
1Hermes is the default engine and JSC has been moved to community support.
2Please remove the USE_HERMES=0, as it is not supported anymore.
JavaScriptCore has moved to the community-maintained @react-native-community/javascriptcore package. Remove USE_HERMES=0 as the message says. If you really need JSC, install it following the community package’s instructions. To check whether you’re on Hermes, test !!global.HermesInternal in JS.
Since 0.84 the default engine is Hermes V1. The 0.84 release notes give an environment variable to fall back to the old Hermes, but newer pod scripts always enable V1, so check the release notes for your version.
8. Crash on launch: Wrong bytecode version
In a Release build, the JS is first compiled to bytecode with hermesc. If that hermesc and the Hermes engine linked into the app are different versions, the app crashes on launch and the log shows Wrong bytecode version. This usually happens when you upgrade RN and only update node_modules without running pod install again, so the old hermes-engine is still in Pods.
After upgrading, run pod install again in the ios folder, then do a clean build.
What if Metro can’t connect or the JS bundle is missing?
9. The device can’t connect to Metro
A Debug build loads JS from the Metro dev server on your computer at launch. If it can’t connect, you get a red screen saying Could not connect to development server. React Native’s docs require the phone and computer to be on the same Wi-Fi and able to reach each other. Check in this order.
- Metro is still running and the terminal shows no errors.
- The phone and computer are on the same network. Guest networks and networks with client isolation don’t work, so try your phone’s hotspot instead.
- Your computer’s firewall allows inbound connections on port 8081.
- The first time the app launches, iOS asks whether it may find devices on your local network. Tap Allow. If you tapped the wrong button, turn it on in Settings > Privacy & Security > Local Network.
10. Release build shows a white screen or crashes
A Release build doesn’t connect to Metro, so the JS must be bundled into main.jsbundle inside the app ahead of time. The Bundle React Native code and images build phase does this, and if it fails the app has no JS. The build log contains a line like this.
1error: File .../main.jsbundle does not exist. Your environment is misconfigured as Metro was not able to produce the bundle so your release application won't work!
There are three common causes. The build environment can’t find node, and the log says Can't find the 'node' binary to build the React Native bundle. Add a line export NODE_BINARY=<absolute path to node> to ios/.xcode.env.local. SKIP_BUNDLING is set in the environment, so remove it. Or the JS has a syntax or import error and Metro fails to bundle it, so scroll up the log to the first JS error.
To check whether an .ipa contains the bundle, copy it, rename the copy to .zip, extract it, and look for main.jsbundle under Payload/YourApp.app/.
How do I fix project configuration and upgrade errors?
11. use_frameworks conflicts
Some libraries, commonly Firebase and similar SDKs, require pods to be integrated as frameworks. The RN template’s Podfile already supports turning this on with the USE_FRAMEWORKS environment variable, so you don’t need to edit the Podfile.
1USE_FRAMEWORKS=static pod install
Prefer static. With dynamic, or a bare use_frameworks! written directly in the Podfile, you’re more likely to hit errors like transitive dependencies that include statically linked binaries and duplicate symbols. After switching, delete the Pods folder in ios before running pod install, because leftover build products cause strange link errors. Everyone on the team and CI must use the same value.
12. Build errors after upgrading RN
Upgrading RN isn’t just changing the version in package.json. AppDelegate, Podfile and Info.plist in the ios folder have to follow the template too. Use the official Upgrade Helper, pick your current and target versions, compare the differences file by file, apply them, then run pod install.
When upgrading to 0.88, watch for one more thing. The 0.88 release notes say UIKit apps built with the iOS 27 SDK must use the UIScene lifecycle or they won’t launch. 0.88 adds SceneDelegate support for this, and the community template now uses SceneDelegate. When you migrate, move your entry point into SceneDelegate following the template and add UIApplicationSceneManifest to Info.plist.
How do I troubleshoot these errors on Windows and Linux?
When you use KXBuild for React Native iOS app development on Windows or Linux, run doctor with the project path first, then pod install in the ios folder, and build the .xcworkspace. The network checks in problem 9 apply too. For the command that opens port 8081 in Windows Firewall and the full workflow, see Build a React Native iOS app on Windows and run it on your iPhone. If a Run Script phase fails, run doctor again with the project path and see Troubleshooting. For any other React Native New Architecture error, work through the summary table above.
FAQ
Can I still turn off the React Native New Architecture?
Not since 0.82. Running pod install with RCT_NEW_ARCH_ENABLED=0 on iOS is ignored, and the app still runs on the New Architecture. For projects that can’t leave the old architecture yet, the official advice is to stay on 0.81 or Expo SDK 54 until migration is done.
How do I tell whether a third-party library supports the New Architecture?
Search for it on reactnative.directory and see whether it’s marked as supported, then check whether its package.json has codegenConfig. If neither, look for adoption plans in the library’s issues, and replace it if it’s no longer maintained.
What’s the minimum iOS version for React Native 0.88?
In 0.88’s CocoaPods scripts, min_ios_version_supported is 15.1, and the template Podfile uses it directly. If a library needs more, follow the library and set the Podfile and the app target’s deployment target to the same value.
How do I fix No such module ‘ReactAppDependencyProvider’?
Codegen generates this module under ios/build/generated/ios during pod install. It goes missing after you delete ios/build or switch branches. Run pod install again in the ios folder.
Why does my React Native Release build show a white screen?
Usually the JS bundle isn’t in the app. Look for errors in the Bundle React Native code and images phase of the build log. Common causes are node not being found, SKIP_BUNDLING being set, or the JS failing to bundle. Extract the .ipa to confirm the app contains main.jsbundle.