Missing dSYM for Flutter.framework in iOS Archive

Problem Statement

When distributing or validating a Flutter iOS app archive in Xcode, you may encounter this error:

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

This occurs because Xcode cannot locate debugging symbols (Flutter.framework.dSYM) needed for crash reports. Without these symbols, app distribution/validation fails.

Solutions

1. Add Build Phase Run Script (Recommended)

Cause: Xcode isn't automatically generating the dSYM during build
Solution: Add a custom script phase

1. In Xcode:

   • Select your target ➔ Build Phases
   • Click + ➔ New Run Script Phase

2. Add this script:

if [ -d "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Flutter.framework" ]; then
    echo "Generating dSYM for Flutter.framework"
    dsymutil "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Flutter.framework/Flutter" -o "${BUILT_PRODUCTS_DIR}/Flutter.framework.dSYM"
fi

3. Verify:
   • Ensure the script runs after frameworks are built
   • Rebuild archive and validate

Note: For other frameworks (e.g., WebRTC.framework), replace "Flutter" with the framework name in both paths.

For Hermes Engine Users (React Native)

Add this separate script phase:

set -euo pipefail

HERMES_BIN="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/hermes.framework/hermes"
HERMES_DSYM="${DWARF_DSYM_FOLDER_PATH}/hermes.framework.dSYM"

if [ -e "$HERMES_BIN" ] && [ ! -e "$HERMES_DSYM" ]; then
  echo "🛠 Generating dSYM for Hermes..."
  /usr/bin/dsymutil "$HERMES_BIN" -o "$HERMES_DSYM"
fi

Place this phase after [CP] Embed Pods Frameworks.

2. Update Flutter

Cause: Outdated Flutter versions may have dSYM generation bugs

flutter upgrade
flutter clean

If using FVM:

fvm flutter upgrade

3. Manually Add Missing dSYM

Use this if automated methods fail:

# 1. Find the framework
find ~/Library/Developer/Xcode/DerivedData -name "Flutter.framework"

# 2. Generate dSYM (replace [path] with actual location)
xcrun dsymutil -o ~/Desktop/Flutter.framework.dSYM /[path]/Flutter.framework/Flutter

# 3. Open archive package
#    - Xcode ➔ Organizer ➔ Right-click archive ➔ Show in Finder
#    - Right-click .xcarchive ➔ Show Package Contents

# 4. Add dSYM
#    - Copy ~/Desktop/Flutter.framework.dSYM
#    - Paste into dSYMs folder within .xcarchive

4. Shorebird-specific Fix (If Using Shorebird)

1. Download Flutter.dSYM from Shorebird Console
2. Add it to your archive's dSYMs folder (see Method 3, Step 4)

Best Practices

1. Regular Updates: Keep Flutter current with flutter upgrade
2. Script Order: Ensure dSYM generation phases run before embedding frameworks
3. Error Validation: Always check UUIDs match in the error logs
4. Relevant Solutions: Use Hermes-specific solutions only if Hermes engine is active

Verifying Success

After applying these solutions:

1. Rebuild archive (Product ➔ Archive)
2. Attempt validation/distribution
3. Check .xcarchive package contents to ensure Flutter.framework.dSYM exists