React Native init stops with 'Failed to install CocoaPods dependencies'
Error: Failed to install CocoaPods dependencies for iOS project, which is required by this template.Short answer
The init command only reports that its pod step failed; the real error is hidden. Create the project without the pod step, then run bundle install and bundle exec pod install inside ios to see the actual message. It usually points to Xcode command line tools, a broken CocoaPods gem, or a pinned CocoaPods version.
Fix it fast
1Find out which cause you have
Run the pod step yourself so the underlying error shows. The project files already exist; only the pod step failed.
cd MyApp bundle install cd ios && bundle exec pod install2Match what you see, then jump to its fix
- 1
The manual run fails while compiling a gem or cannot find build toolsThe Xcode command line tools are missing or not selectedFix - 2
pod: command not found, or a Ruby load error, right after a system updateThe CocoaPods gem stopped working after a macOS or Ruby updateFix - 3
The manual run builds an old or globally installed pod that differs from the project's GemfileA CocoaPods version the template excludes is installedFix
- 1
What does the error look like?
Error: Failed to install CocoaPods dependencies for iOS project, which is required by this template.
Cause 1 of 3
The Xcode command line tools are missing or not selected
1Check
The setup guide asks for the latest Xcode and for a Command Line Tools version chosen in Xcode's Locations settings.
xcode-select -p
xcodebuild -version2Fix
Open Xcode, go to Settings, then Locations, and pick the most recent Command Line Tools version in the dropdown.
xcodebuild -version3Verify
bundle exec pod install runs without a compile error.
cd ios && bundle exec pod installConfirmed by reactnative.dev
Cause 2 of 3
The CocoaPods gem stopped working after a macOS or Ruby update
1Check
CocoaPods is a Ruby gem, and the CocoaPods troubleshooting guide says an installed gem can stop working after a macOS upgrade.
which pod
gem list cocoapods2Fix
Uninstall and reinstall the gem, as the guide describes. If gem install fails with a permission error, the guide gives sudo gem install -n /usr/local/bin cocoapods for that case.
gem uninstall cocoapods
gem install cocoapods3Verify
pod runs and prints its version.
pod --versionConfirmed by guides.cocoapods.org
Cause 3 of 3
A CocoaPods version the template excludes is installed
1Check
The template's Gemfile requires CocoaPods 1.13 or newer and excludes 1.15.0 and 1.15.1, which cause build failures. Running a global pod can bypass that pin.
pod --version
bundle exec pod --version2Fix
Install the Gemfile's gems and run pod through Bundler, so the pinned version is used.
bundle install
cd ios && bundle exec pod install3Verify
bundle exec pod --version prints a version the Gemfile allows.
bundle exec pod --versionConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Create projects with --skip-install or --install-pods false when you want the pod step to run in a terminal you can read.
- Use bundle exec pod install in an existing project, as the template's README does, so the Gemfile version is used.
- Keep Xcode and its command line tools current before starting a new project.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Running pod on a React Native project fails with can't find gem cocoapods
can't find gem cocoapods (>= 0.a) with executable pod
The pod command exists, but the Ruby that is running it has no CocoaPods gem.
3 causes, each with a fixMobile apps
Axios request works on iOS or in a browser but fails on Android with Network Error
AxiosError: Network Error
A React Native app has no CORS, so on Android a Network Error usually means the request never reached the server.
3 causes, each with a fixMobile apps
Axios returns Network Error in a React Native app on iPhone or the iOS Simulator
error.code is ERR_NETWORK and error.response is undefined
A Network Error means iOS stopped the request before any HTTP answer came back.
3 causes, each with a fixMobile apps
backgroundImage: url(...) does nothing in a React Native view
ImageBackground renders an empty area
In React Native the backgroundImage style draws linear and radial gradients, not pictures, so url(...) is ignored.
3 causes, each with a fixMobile apps
A custom font in React Native falls back to the system font
Unrecognized font family 'MyFont'
React Native does not report a missing font, it just draws the system font.
6 causes, each with a fixMobile apps
fetch fails with TypeError: Network request failed in React Native
Network request failed
Network request failed means the request never got an HTTP response, so there is no status code to read.
3 causes, each with a fix