Repository navigation
Description
Summary
On React Native 0.88.1, any Swift target that imports NitroModules fails to compile because
building the cxxreact Clang module cannot find jserrorhandler/ErrorUtils.h. The module itself
is fine — the failure happens in the importers.
Environment
react-native-nitro-modules |
0.37.2 |
react-native-nitro-sound |
0.2.20 |
react-native |
0.88.1 |
| Xcode | 26.6 |
| CocoaPods | 1.16.2 |
| iOS deployment target | 15.1 |
Possibly relevant Podfile configuration — I have not verified whether the issue reproduces
without these, and it may be why not everyone hits it:
use_frameworks! :linkage => :static
ENV['RCT_USE_PREBUILT_RNCORE'] = '0' # React Native core built from source
$RNFirebaseAsStaticFramework = trueWhat happens
node_modules/react-native/ReactCommon/cxxreact/ErrorUtils.h:12:10:
error: 'jserrorhandler/ErrorUtils.h' file not found
node_modules/react-native-nitro-modules/cpp/views/ReactNativeCore.hpp:8:10:
error: could not build module 'cxxreact'
<unknown>:0: error: could not build Objective-C module 'NitroModules'
pod install succeeds and prints [NitroModules] Found react-native 0.88.1 (88), so detection
is fine; only the build fails.
Why
In React Native 0.88, ReactCommon/cxxreact/ErrorUtils.h includes <jserrorhandler/ErrorUtils.h>.
The React-jserrorhandler pod does not publish that header under Pods/Headers/Public:
node_modules/react-native/ReactCommon/jserrorhandler/ErrorUtils.h exists
ios/Pods/Headers/Public/React-jserrorhandler/ empty
So the include only resolves when the ReactCommon root is on the header search path.
What does not fix it, and why it is worth knowing
Two changes to NitroModules.podspec that look right both fail:
- Adding
s.dependency 'React-jserrorhandler'— CocoaPods builds the pod but still publishes no
header, so the include is unchanged. (It did drop the error count from 6 to 3 in my build, but
the root error remained.) - Appending the
ReactCommonroot topod_target_xcconfig'sHEADER_SEARCH_PATHS— I confirmed
the path reaches the generatedNitroModules.debug.xcconfig, and it still fails.
The reason is the last line of the error: <unknown>:0: error: could not build Objective-C module 'NitroModules' comes from the Swift frontend of the importing target, not from NitroModules
compiling itself. A Clang module is built with the header search paths of whatever imports it, so
anything set on NitroModules' own target cannot reach NitroSound or any other Swift consumer.
Workaround
Setting the path on every target, from the app's Podfile:
post_install do |installer|
installer.pods_project.targets.each do |target|
react_common = '"${PODS_ROOT}/../../node_modules/react-native/ReactCommon"'
target.build_configurations.each do |config|
paths = config.build_settings['HEADER_SEARCH_PATHS']
paths = paths.is_a?(Array) ? paths.join(' ') : (paths || '$(inherited)')
unless paths.include?('node_modules/react-native/ReactCommon')
config.build_settings['HEADER_SEARCH_PATHS'] = "#{paths} #{react_common}"
end
end
end
endWith this, the build succeeds and Sound initialises correctly at runtime. Without it, on 0.37.2
the build fails; on 0.35.10 the build succeeds but Nitro reports
installJSIBindingsWithRuntime: was not called - JSI Bindings could not be installed! and the
HybridObject never exists.
Note on 1.0.0-alpha
I looked at 1.0.0-alpha.nightly.120 as an alternative. It moves to Swift Package Manager and
sets s.ios.deployment_target = "16.0", so it is not an option for apps still supporting iOS 15.
What I am unsure about
- Whether this reproduces without
use_frameworks! :linkage => :static. - Whether the right fix belongs in nitro at all, or in
React-jserrorhandler's podspec publishing
its headers. The workaround above is in app space because that is where it provably works, not
because it is the correct home for it.
Activity
docs: say Xcode 27 needs Nitro's #1824 fix to launch on iOS below 18
docs: say Xcode 27 needs Nitro's #1824 fix to launch on iOS below 18
chore(release): 0.2.0-next.81 [skip ci]
csheppard commentedon Nov 14, 2026
We hit this with
use_frameworks! :linkage => :dynamic, so it isn't limited to static frameworks. The header workaround above gets the build through.Environment
react-native-nitro-modulesreact-native-unistylesreact-nativebuildReactNativeFromSource: true)useFrameworks: "dynamic"via expo-build-propertiesWe needed dynamic frameworks because
@stripe/stripe-react-native0.84+ resolves the Stripe iOS SDK through SPM (Stripe stopped publishing to CocoaPods ahead of trunk going read-only on Dec 2), and that requires dynamic linkage. Other libraries will probably need the same once trunk goes read-only.What happens
'jserrorhandler/ErrorUtils.h' file not found→could not build module 'cxxreact'→could not build module 'NitroModules', during Clang dependency scanning for theNitroModulestarget.post_installHEADER_SEARCH_PATHSworkaround from this issue:** BUILD SUCCEEDED **(Release, iOS Simulator).Correction: an earlier version of this comment said that under dynamic linkage the app then failed at launch with
ReferenceError: Property 'NitroModules' doesn't exist, and that static linkage ran fine. Our statically linked Release build fails at launch the same way, so that failure isn't specific to dynamic linkage or to this issue. I've removed it from this comment.