TL;DR

I repeatedly failed building a React Native 0.81 + RNFirebase Messaging iOS app on an Apple Silicon (M1/arm64) machine due to a combination of:

• C/C++ header include-order pitfalls (RCT-Folly, Yoga, glog) amplified by custom header tweaks
• CocoaPods quirks (bundled version vs system pod, encoding)
• Firebase module map exposure (missing modular headers)

The final green build came from reverting to standard RN 0.81 Pod settings, keeping architecture defaults, and enabling modular headers for GoogleUtilities, FirebaseCoreInternal, and FirebaseCore — plus using the system pod to avoid a known Bundler/CocoaPods issue.

---

Environment

• Machine: Apple Silicon (M1, arm64)
• macOS: 15.6.x (Darwin 24.6.0)
• Xcode: 16.1 (Build 17A400), iPhoneSimulator SDK 26.0
• React Native: 0.81.x (Hermes enabled)
• CocoaPods:
  • Bundled pod had an intermittent “pathname contains null byte” bug
  • System pod worked reliably
• iOS Deployment Target: 15.1
• Firebase: RNFirebase (App + Messaging)

---

Symptoms Observed

1. Yoga headers not found, e.g. 'yoga/Yoga.h' file not found.
2. RCT-Folly errors referencing <cstdio>/<cstring>/<cmath> with C headers taking precedence over libc++ wrappers (leading to FILE/pthread issues).
3. glog mutex-related build breaks (mutex.h/pthread macros).
4. CocoaPods “pathname contains null byte” during pod install with the bundled Ruby/CocoaPods.
5. Firebase compile errors: Module 'FirebaseCore' not found in FirebaseInstallations sources.
6. Intermittent Xcode/Ruby locale hiccups (resolved by ensuring UTF-8 env and re-running).

---

Root Causes

• Over-customized header search paths for Pods (global HEADER_SEARCH_PATHS, SYSTEM_HEADER_SEARCH_PATHS, OTHER_CPLUSPLUSFLAGS, -isystem) changed include order, making C headers shadow libc++ and breaking RCT-Folly.
• Attempting to “fix” headers globally (Pods + App target) unintentionally polluted multiple targets (glog, Yoga, Folly, React-*), causing cascading failures.
• Using frameworks / modular header toggles globally introduced module map mismatches for Swift pods and RNFirebase transitive deps.
• Bundled CocoaPods path/encoding edge-case (“pathname contains null byte”) blocked deterministic installs.
• FirebaseCore module was not exposed as a modular header in our setup, causing Module 'FirebaseCore' not found.

---

What Actually Fixed It

• Reset Podfile to the standard RN 0.81 shape; don’t globally alter header search paths or C++ flags.
• Keep Legacy Architecture (disable New Architecture explicitly) and target iOS 15.1 to satisfy React Native codegen.
• Avoid forcing use_frameworks!; stick to default static libraries.
• Make only the necessary Firebase pods modular:
  • GoogleUtilities, FirebaseCoreInternal, and critically FirebaseCore.
• Use system pod install (not Bundler) to avoid the “pathname contains null byte” error.
• Build on an arm64 simulator (M1 host), letting headermap/modulemaps drive includes.
• Do not add Yoga paths manually; rely on Yoga’s own modulemap and RN defaults.
• Only if needed: for glog, ensure pthread defines via target-specific settings (but avoid global hacks).

Result: Build succeeded. App runs, and FCM token logs as expected.

---

Minimal Podfile (Working Shape)

# Resolve react_native_pods.rb with node to allow for hoisting
require Pod::Executable.execute_command('node', ['-p',
  'require.resolve(
    "react-native/scripts/react_native_pods.rb",
    {paths: [process.argv[1]]},
  )', __dir__]).strip

platform :ios, '15.1'
ENV['RCT_NEW_ARCH_ENABLED'] = '0'
prepare_react_native_project!

target 'EchoReadApp' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  # Ensure Swift pods expose module maps for Firebase
  pod 'GoogleUtilities', :modular_headers => true
  pod 'FirebaseCoreInternal', :modular_headers => true
  pod 'FirebaseCore', :modular_headers => true

  post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )
    # No global header/cxx overrides here. Keep RN defaults.
  end
end

Key point: No global use_frameworks!, no global HEADER_SEARCH_PATHS/SYSTEM_HEADER_SEARCH_PATHS hacks, no project-wide -isystem injections.

---

Verified Working Build Path

1. Clean CocoaPods integration

   cd ios
   pod deintegrate
   rm -rf build Pods Podfile.lock
   

2. Install with system CocoaPods

   pod install
   

3. Xcode clean + build (arm64 simulator)

   xcodebuild \
     -workspace EchoReadApp.xcworkspace \
     -scheme EchoReadApp \
     -sdk iphonesimulator \
     -configuration Debug \
     -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
     ONLY_ACTIVE_ARCH=YES \
     build
   

4. Run the app (will print FCM token on first launch after permission)

   # ensure Metro is running
   npm start   # or: npx react-native start
   
   # then run on simulator
   npx react-native run-ios --simulator "iPhone 17 Pro"
   

---

Guidance for Future Changes

• Prefer target-scoped tweaks over global Podfile-wide settings.
• Let RN’s react_native_post_install do the heavy lifting; avoid overriding header maps.
• For Firebase on RN iOS, keep GoogleUtilities, FirebaseCoreInternal, and FirebaseCore as modular headers when using static libs.
• On Apple Silicon, prefer arm64 simulators and avoid x86_64-specific workarounds.
• If pod install misbehaves under Bundler, try system pod as a fallback.
• Treat any “fix” that alters global include order with suspicion; verify by reverting to defaults first.