Skip to content

NitroModules fails to build on React Native 0.88: 'jserrorhandler/ErrorUtils.h' file not found #2052

Open

Description

@drumsSandoval

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 = true

What 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:

  1. 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.)
  2. Appending the ReactCommon root to pod_target_xcconfig's HEADER_SEARCH_PATHS — I confirmed
    the path reaches the generated NitroModules.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
end

With 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

  1. csheppard commented on Nov 14, 2026

    @csheppard

    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-modules 0.37.2
    react-native-unistyles 3.8.1 (the only Nitro consumer)
    react-native 0.88.1, built from source (buildReactNativeFromSource: true)
    Expo SDK 58.0.23
    Xcode / CocoaPods 27.2 / 1.17.0
    Linkage useFrameworks: "dynamic" via expo-build-properties

    We needed dynamic frameworks because @stripe/stripe-react-native 0.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

    1. Without the workaround: same build failure as reported, 'jserrorhandler/ErrorUtils.h' file not found → could not build module 'cxxreact' → could not build module 'NitroModules', during Clang dependency scanning for the NitroModules target.
    2. With the post_install HEADER_SEARCH_PATHS workaround 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions