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

[robertying]

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 Hermes 0.14 artifact breaks Mac Catalyst build hermes#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

[Arkkeeper]

The same problem. Interestingly, if I try to build these xcframeworks manually using node /scripts/ios-prebuild/ and node scripts/releases/prepare-ios-prebuilds.js, their structure remains correct. Perhaps the problem is again related to how Github Actions work.