Troubleshooting Firebase Expo EAS iOS Build Error

This guide provides steps to resolve the "Unknown error" in the Install pods build phase during an Expo EAS build for iOS with Firebase.

1. Check Podfile Configuration

Ensure your Podfile is correctly set up for Firebase. Below is a sample Podfile for an Expo project:

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-firebase/app'

platform :ios, '13.0'

target 'YourAppName' do
  config = use_native_modules!
  use_react_native!(
    :path => '../node_modules/react-native',
    :hermes_enabled => false
  )
  pod 'Firebase/Analytics', '~> 10.24.0'
  pod 'FirebaseCore', '~> 10.24.0'
  # Add other Firebase pods as needed, e.g., 'Firebase/Firestore'
end

Verify Firebase pod versions are compatible with your React Native and Expo versions (e.g., @react-native-firebase/app@^18.0.0).
Replace YourAppName with your actual app name.

2. Inspect EAS Build Logs

Check the detailed logs in the EAS build dashboard under ios/Pods/Logs for the Install pods phase. Look for:

CocoaPods version mismatch: Ensure the EAS CocoaPods version (e.g., 1.15.2) matches your local setup (pod --version).
Missing or incompatible pods: Errors like "pod not found" or version conflicts (e.g., GoogleUtilities issues).
Network issues: Failures like Failed to fetch podspec due to connectivity problems.

3. Common Fixes

Clear Pod Cache

Add a pre-install hook in eas.json to clear the Pod cache:

{
  "build": {
    "production": {
      "ios": {
        "prebuildCommand": "rm -rf ~/Library/Caches/CocoaPods && pod cache clean --all"
      }
    }
  }
}

Update CocoaPods

Force CocoaPods to a compatible version in eas.json:

{
  "build": {
    "production": {
      "ios": {
        "prebuildCommand": "gem install cocoapods -v 1.15.2"
      }
    }
  }
}

Pin Firebase Versions

Explicitly pin Firebase pods in the Podfile to avoid mismatches:

pod 'Firebase/Analytics', '~> 10.24.0'
pod 'FirebaseCore', '~> 10.24.0'

Check `package.json`

Ensure @react-native-firebase/* packages are compatible. Run:

npm outdated
npm install @react-native-firebase/app@latest

4. Expo-Specific Considerations

Managed Workflow

If using expo-firebase-* packages, avoid mixing with @react-native-firebase. Configure in app.json:

{
  "expo": {
    "plugins": [
      ["expo-firebase-analytics", { "iosAnalyticsCollectionEnabled": true }]
    ]
  }
}

Bare Workflow

For bare workflow or custom dev clients, configure expo-build-properties in app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "13.0"
          }
        }
      ]
    ]
  }
}

5. Debugging Tips

Reproduce Locally: Run npx expo run:ios or pod install in the ios directory to identify errors.
Check XCode Compatibility: Use XCode 16+ for Firebase SDK compatibility.
Verify Firebase Setup: Ensure GoogleService-Info.plist is added to your iOS project via app.json or XCode.

6. Community Workarounds

Force Clean Build: Trigger a new EAS build with:

eas build --platform ios --clear-cache

Downgrade Firebase Pods: If the latest Firebase pods cause issues, try downgrading (e.g., pod 'Firebase/Analytics', '~> 10.20.0').

Additional Notes

Always verify Firebase pod versions against the official documentation or GitHub releases.
If issues persist, share detailed logs from the EAS dashboard on forums like X or Expo’s community for specific advice.

decagondev/POD-TROUBLESHOOTING.md