Fix: undefined symbols _RNSBottomTabsCls in React Native 0.76

Context#

• “react-native-screens”: “^4.13.1”,
• “react-native”: “0.76.8”,
• Xcode: 16.4

Error Log#

Xcode build error:

Expanded error:

ld: warning: ignoring duplicate libraries: '-lc++', '-lz'

ld: warning: search path '*********************/Library/Developer/Xcode/DerivedData/hsp-fmfmhonkiseyvxerinenzbgzrnpb/Build/Products/Release-iphonesimulator/FBReactNativeSpec' not found

ld: warning: search path ''*********************/Library/Developer/Xcode/DerivedData/hsp-fmfmhonkiseyvxerinenzbgzrnpb/Build/Products/Release-iphonesimulator/Folly' not found

ld: warning: Could not find or use auto-linked framework 'CoreAudioTypes': framework 'CoreAudioTypes' not found

ld: warning: Could not parse or use implicit file '/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk/System/Library/Frameworks/SwiftUICore.framework/SwiftUICore.tbd': cannot link directly with 'SwiftUICore' because product being built is not an allowed client of it

Undefined symbols for architecture arm64:

  "_RNSBottomTabsCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

  "_RNSBottomTabsScreenCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

  "_RNSScreenStackHostCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

  "_RNSSplitViewHostCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

  "_RNSSplitViewScreenCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

  "_RNSStackScreenCls", referenced from:

      _RCTThirdPartyFabricComponentsProvider in RCTFabric[42](RCTThirdPartyFabricComponentsProvider.o)

ld: symbol(s) not found for architecture arm64

clang++: error: linker command failed with exit code 1 (use -v to see invocation)

Root Cause#

The build error occurred due to experimental Fabric components in react-native-screens v4.12.0+ that aren’t fully compatible with React Native 0.76.x.

The Technical Details:

1. Experimental “Gamma” Components: Starting from v4.12.0, react-native-screens introduced experimental native components like:
   • RNSBottomTabsCls
   • RNSBottomTabsScreenCls
   • RNSScreenStackHostCls
   • RNSSplitViewHostCls These require building with ENV['RNS_GAMMA_ENABLED'] = '1' flag.
2. Fabric Registration Issue: In React Native 0.76.x with Fabric enabled, there’s a problem with how third-party native components are registered. The codegen generates RCTThirdPartyFabricComponentsProvider that references these experimental components, but they’re not properly linked during the build process.
3. Architecture Mismatch: Your project had:
   • Fabric enabled initially (fabric_enabled => true)
   • react-native-screens 4.13.1 with experimental components
   • React Native 0.76.8 which has incomplete support for these new components
4. Why 4.11.0 Works: Version 4.11.0 predates these experimental components, so it doesn’t try to register RNSBottomTabsCls and similar classes that cause the undefined symbols error.

The Fix#

Downgrade react-native-screens to a lower version 4.11.0 (Released May 27, 2024)

Why 4.11.0 is the best choice:

1. Stable and Mature - Released in May 2024, it’s had several months of real-world testing
2. Major iOS Bug Fixes including:
   • Fixed pressables in header not working with modal presentation
   • Fixed TouchableOpacity issues on screens
   • Fixed sporadic screen content jumps
   • Fixed header back button issues
   • Improved gesture handling in modals
3. Not Too New - Avoids the experimental features introduced in 4.12+ (like native bottom tabs that cause your current issue)
4. Compatible - Fully supports React Native 0.76+ with Paper (old architecture)

Why NOT other versions:

• 4.9.0: Had build issues with USE_FRAMEWORKS=dynamic
• 4.9.1: Only a patch fix for 4.9.0 issues
• 4.10.0: Fewer bug fixes than 4.11.0
• 4.12.0+: Introduces experimental native bottom tabs (the source of your RNSBottomTabsCls errors)
• 4.13.0-4.13.1: Too new with experimental features requiring RNS_GAMMA_ENABLED

Installation Command:

yarn add react-native-screens@4.11.0

Summary#

This linking error happens when react-native-screens 4.12+ introduces experimental Fabric components that aren’t fully compatible with React Native 0.76. The quickest solution is to downgrade to version 4.11.0, which predates these experimental features while still being stable and feature-rich.

References#

• https://github.com/software-mansion/react-native-screens/releases ↗