[0.84.0] [iOS] Mac Catalyst build failed with bundle format is ambiguous (could be app or framework)

Inizia con il reproducer obbligatorio e i passaggi di build di Catalyst elencati, quindi ispeziona i percorsi generati di ReactNativeDependencies.xcframework, React.xcframework e hermesvm.framework sotto ios/Pods. Confronta i loro symlink dei framework Catalyst e le posizioni dei bundle con le strutture previste nell’issue. Il lavoro è completato quando i framework precompilati corretti vengono installati e il progetto React Native viene compilato per una destinazione Mac Catalyst senza l’errore ambiguo relativo al formato del bundle.

Issues

Upgrading to 0.84 broke build for Mac Catalyst, with the error "bundle format is ambiguous (could be app or framework)"

There are several issues:

1. Hermes 250829098.0.7 (shipped with 0.84) has the wrong symlinks in the framework for Mac Catalyst. (This has been fixed in 250829098.0.8; see https://github.com/facebook/hermes/issues/1883)

2. React Native pre-built dependencies also have the wrong symlinks as well as invalid structures.

   ls -al ReactNativeDependencies.xcframework/ios-arm64_x86_64-maccatalyst/ReactNativeDependencies.framework

   -rw-r--r--  1 rying  staff  6963960 Feb 11 06:48 ReactNativeDependencies
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_boost.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_folly.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_glog.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 Resources
   drwxr-xr-x  4 rying  staff      128 Feb 11 06:48 Versions
   

   ls -al React.xcframework/ios-arm64_x86_64-maccatalyst/React.framework

   drwxr-xr-x  63 rying  staff       2016 Feb 11 07:15 Headers
   drwxr-xr-x   3 rying  staff         96 Feb 11 07:15 Modules
   -rw-r--r--   1 rying  staff  114967784 Feb 11 07:14 React
   drwxr-xr-x   3 rying  staff         96 Feb 11 07:14 Resources
   drwxr-xr-x   4 rying  staff        128 Feb 11 07:14 Versions
   

Expectations

1. The correct symlinks shoud look like this

   lrwxr-xr-x  1 rying  staff   40 Feb 12 21:37 ReactNativeDependencies -> Versions/Current/ReactNativeDependencies
   lrwxr-xr-x  1 rying  staff   26 Feb 12 21:37 Resources -> Versions/Current/Resources
   drwxr-xr-x@ 4 rying  staff  128 Feb 12 21:37 Versions
   

2. ReactNativeDependencies_boost.bundle etc. cannot be in the directory ReactNativeDependencies.framework. These bundles need to be moved to under Versions/Current/Resources instead.

Workarounds

1. Download the newer version of Hermes 250829098.0.8 from https://repo1.maven.org/maven2/com/facebook/hermes/hermes-ios and use it for pod install: HERMES_ENGINE_TARBALL_PATH=/Users/rying/Downloads/hermes-ios-250829098.0.8-hermes-ios-debug.tar.gz pod install

2. Here is a script that fixes the pre-built dependencies' framework structures:

   pushd ios/Pods/hermes-engine/destroot/Library/Frameworks/universal/hermesvm.xcframework/ios-arm64_x86_64-maccatalyst/hermesvm.framework
   rm -r hermesvm Resources        
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/hermesvm hermesvm
   pushd Versions && rm -r Current && ln -s 1 Current && popd
   popd
   
   pushd ios/Pods/React-Core-prebuilt/React.xcframework/ios-arm64_x86_64-maccatalyst/React.framework
   rm -r React Resources
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/React React
   pushd Versions && rm -r Current && ln -s A Current && popd
   popd
   
   pushd ios/Pods/ReactNativeDependencies/framework/packages/react-native/ReactNativeDependencies.xcframework/ios-arm64_x86_64-maccatalyst/ReactNativeDependencies.framework
   rm -r ReactNativeDependencies Resources
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/ReactNativeDependencies ReactNativeDependencies
   pushd Versions && rm -r Current && ln -s A Current && popd
   mv ReactNativeDependencies_*.bundle Resources
   popd
   

Steps to reproduce

1. Create a new RN project with CLI
2. Install node modules, pods, etc.
3. Open Xcode and enable Mac Catalyst support by adding it as a destination
4. Run the project with the Mac Catalyst as the target
5. Observe build errors

React Native Version

0.84.0

Affected Platforms

Build - MacOS

Output of npx @react-native-community/cli info

System:
  OS: macOS 26.3
  CPU: (10) arm64 Apple M1 Pro
  Memory: 1.13 GB / 16.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 25.6.1
    path: /Users/rying/.nvm/versions/node/v25.6.1/bin/node
  Yarn: Not Found
  npm:
    version: 11.9.0
    path: /Users/rying/.nvm/versions/node/v25.6.1/bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /opt/homebrew/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 25.2
      - iOS 26.2
      - macOS 26.2
      - tvOS 26.2
      - visionOS 26.2
      - watchOS 26.2
  Android SDK: Not Found
IDEs:
  Android Studio: 2025.2 AI-252.28238.7.2523.14688667
  Xcode:
    version: 26.3/17C519
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.18
    path: /opt/homebrew/Cellar/openjdk@17/17.0.18/libexec/openjdk.jdk/Contents/Home/bin/javac
  Ruby:
    version: 2.6.10
    path: /usr/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 20.1.1
    wanted: 20.1.1
  react:
    installed: 19.2.3
    wanted: 19.2.3
  react-native:
    installed: 0.84.0
    wanted: 0.84.0
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

Stacktrace or Logs

N/A

MANDATORY Reproducer

https://github.com/robertying/rn84-mac-catalyst-build-error

Screenshots and Videos

No response