Skip to main content

iOS and CocoaPods Errors in React Native Apps

iOS build errors usually come from pods being out of sync, stale Xcode derived data, missing Firebase config files, local Node path issues, signing, or native dependency changes that were not followed by a pod install.

Quick Answer​

Run commands from the app folder, reinstall pods, restart Metro, and rebuild iOS.

corepack enable
yarn install
bundle exec pod install --project-directory=ios
yarn start --reset-cache
yarn ios

If the app has no Gemfile, install pods from the ios folder:

cd ios
pod install
cd ..

Before You Debug iOS​

Check:

node --version
yarn --version
xcodebuild -version
pod --version

Open the workspace, not the project, when debugging in Xcode:

open ios/*.xcworkspace

Pods Are Out Of Sync​

Run pod install after:

  • changing dependencies;
  • updating native packages;
  • replacing Firebase config files that are referenced by the native project;
  • pulling app package updates;
  • switching branches.
bundle exec pod install --project-directory=ios

If pods still fail:

cd ios
pod deintegrate
pod install
cd ..

Use pod deintegrate sparingly. Do not delete native project files as a first step.

Xcode Cannot Find Node​

If Xcode cannot locate Node, create a local-only file:

echo 'export NODE_BINARY=/opt/homebrew/bin/node' > ios/.xcode.env.local

Adjust the path if your Node binary is elsewhere:

which node

Do not commit ios/.xcode.env.local.

Missing GoogleService-Info.plist​

Firebase-backed apps need the iOS config file in the native target.

  1. Open Firebase Console.
  2. Download GoogleService-Info.plist for the production or development iOS app.
  3. Place it in the expected ios/<AppName>/ target folder.
  4. Clean and rebuild the app.

If the file was added through Xcode, confirm it is included in the app target.

Stale Derived Data​

If Xcode keeps compiling stale files:

  1. In Xcode, choose Product > Clean Build Folder.
  2. If needed, delete Derived Data from Xcode settings.
  3. Rebuild from terminal or Xcode.

Non-modular Include Or Module Build Errors​

These often come from pods, framework settings, native package compatibility, or stale build artifacts.

Start with:

bundle exec pod install --project-directory=ios

Then clean build folder in Xcode and rebuild. Avoid changing Podfile framework settings unless the app package or package maintainer requires it.

Simulator Build Succeeds But App Does Not Open​

Check:

  • Metro is running;
  • the simulator has the app installed;
  • the terminal points to the intended scheme/device;
  • Xcode logs do not show a JavaScript runtime error.

Use Xcode when you need detailed native logs.

Signing And Capabilities​

For release builds, configure:

  • Apple Developer team;
  • bundle identifier;
  • provisioning profile;
  • push notification capability if used;
  • Sign In with Apple if used;
  • associated domains if used.

Debug simulator builds usually do not require production signing.

Verification​

iOS is healthy when:

  • pod install completes;
  • the workspace opens in Xcode;
  • yarn ios installs and launches the app;
  • Metro bundles index.js;
  • Firebase-backed apps find GoogleService-Info.plist;
  • release signing is configured for archive builds.

Next Steps​

FAQ​

Should I open .xcodeproj or .xcworkspace?​

Open .xcworkspace for CocoaPods-based React Native apps.

Should I commit Pods?​

Follow the app package repository rules. In most React Native app packages, Pods is regenerated locally and should not be edited manually.