Missing Hermes dSYM in React Native iOS Archive

Problem Statement

When distributing a React Native iOS app with Hermes engine to the App Store, you may encounter this Xcode error during validation or distribution:

The archive did not include a dSYM for the hermes.framework with the UUIDs. Ensure that the archive's dSYM folder includes a DWARF file for hermes.framework with the expected UUIDs.

This occurs because the build process doesn't automatically include debugging symbols (dSYM) for the Hermes framework. Without these files, Xcode cannot validate the binary, and crash reporting tools can't symbolicate Hermes-related crashes.

Solution

To resolve this, manually generate the Hermes dSYM file using the binary from the official React Native artifacts repository.

Step 1: Identify Your React Native Version

Check your project's package.json for the exact React Native version:

// package.json
"dependencies": {
  "react-native": "0.72.10" // Your version here
}

Step 2: Download Matching Hermes Release

1. Visit the React Native artifacts repository:
   https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/

2. Locate your React Native version folder (e.g., 0.72.10)

3. Download the Hermes iOS release file:
   react-native-artifacts-<version>-hermes-ios-release.tar.gz

Step 3: Extract the Archive

Run this terminal command (adjust version number):

tar -xvzf react-native-artifacts-0.72.10-hermes-ios-release.tar.gz

Step 4: Generate dSYM File

1. Navigate to the framework directory:

   cd react-native-artifacts-0.72.10-hermes-ios-release/destroot/Library/Frameworks/universal/hermes.xcframework/ios-arm64

2. Generate the dSYM file:

   dsymutil hermes.framework/hermes -o hermes.framework.dSYM

Step 5: Include dSYM in Your Project

CRITICAL STEP

Add the generated hermes.framework.dSYM file to your Xcode project:

1. In Xcode, open your project's target settings
2. Go to Build Phases > Copy dSYM Files
3. Add hermes.framework.dSYM to the list
4. Ensure the file exists in your project directory

ios/
├── your-project.xcodeproj
├── hermes.framework.dSYM # Add here
└── ...

Explanation

Why This Error Occurs

• React Native's Hermes engine is precompiled
• Xcode archives don't automatically include third-party framework dSYMs
• UUIDs in the binary must match debugging symbols for validation

Key Requirements

• Version Matching: The Hermes binary must exactly match your React Native version
• Architecture: iOS builds require the ios-arm64 binary variant
• Validation: Xcode verifies dSYM UUIDs during App Store submission

Additional Recommendations

1. Automate the Process: Add a build script to download and generate dSYMs:

   # Example script snippet
   RN_VERSION=$(node -p "require('./package.json').dependencies['react-native']")
   HERMES_URL="https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/${RN_VERSION}/react-native-artifacts-${RN_VERSION}-hermes-ios-release.tar.gz"
   
   curl -L $HERMES_URL -o hermestemp.tar.gz
   tar -xvzf hermestemp.tar.gz
   # Add dsymutil steps from above

2. Crash Reporting Integration: Upload the dSYM to your error tracking service:

   # Sentry example
   sentry-cli upload-dif --include-sources hermes.framework.dSYM
   
   # Firebase Crashlytics
   upload-symbols -gsp GoogleService-Info.plist hermes.framework.dSYM

3. Verify UUID Matching:

   dwarfdump -u hermes.framework.dSYM/Contents/Resources/DWARF/hermes

Best Practices

1. Version Control: Commit Hermes dSYMs to your repository
2. CI/CD Integration: Automate dSYM generation in your build pipeline
3. Fallback: If your React Native version lacks pre-built Hermes artifacts, compile Hermes from source

With the dSYM file properly included, Xcode should successfully validate and distribute your React Native archive to the App Store.