What this usually means
These errors almost always come from one of three root causes: (1) version mismatch between your React Native version and the Podfile's platform or pod versions, (2) a corrupted or stale CocoaPods cache/Specs repo, or (3) an incomplete or misconfigured native dependency that CocoaPods can't resolve. The most common non-obvious culprit is the `ffi` gem, which CocoaPods depends on for loading native extensions—if your Ruby environment is system-managed (e.g., macOS default Ruby), `ffi` often fails silently. Another frequent trap: forgetting to run `npx pod-install` instead of plain `pod install` (the former respects the React Native podspec changes).
The first ten minutes — establish facts before touching code.
- 1Check Ruby version: `ruby -v`. If < 2.7, upgrade via `brew install ruby` and update PATH.
- 2Run `pod repo list` to verify the master spec repo exists and is up to date.
- 3Run `gem list ffi` — if missing or outdated, install with `gem install ffi --user-install`.
- 4Run `cd ios && pod deintegrate && pod cache clean --all` to wipe local state.
- 5Check Podfile platform: `grep platform ios/Podfile` — must match your RN deployment target (e.g., `platform :ios, '12.0'`).
- 6Run `npx react-native doctor` to catch environment issues.
The specific files, logs, configs, and dashboards that usually own this bug.
- search`ios/Podfile` — platform version, pod sources, and `use_frameworks!` flags
- search`ios/Podfile.lock` �� locked versions of every pod, especially React-Core and Flipper
- search`~/.cocoapods/repos/trunk` — the master spec repo, often stale or missing
- search`ios/build/` — stale build artifacts that confuse Xcode
- search`Gemfile.lock` or `Gemfile` — Ruby gem versions, especially cocoapods and ffi
- search`node_modules/react-native/scripts/` — autolinking scripts and podspec helpers
- searchXcode build log (⌘9) — exact linker errors for missing libraries
Practical causes, not theory. These are the things you will actually find.
- warningCocoaPods version < 1.8.0 with a `trunk` repo that requires newer specs
- warningFFI gem not installed or compiled against system Ruby (macOS Monterey+ breaks this)
- warningStale `Pods/` directory or `Podfile.lock` after React Native upgrade
- warningOutdated `react-native` or `react-native-community` podspecs in `node_modules`
- warningWrong deployment target in Podfile (e.g., iOS 9.0 when React Native 0.70+ needs 12.0)
- warningMultiple Xcode versions or command line tools mismatched with `xcode-select -p`
Concrete fix directions. Pick the one that matches your root cause.
- buildUpgrade CocoaPods and FFI: `sudo gem install cocoapods ffi` then `pod repo update`
- buildNuke and restore: `cd ios && pod deintegrate && rm -rf Podfile.lock Pods && pod install --repo-update`
- buildFix Ruby environment: Use `rbenv` or `chruby` with Ruby 3.x, then `gem install cocoapods ffi`
- buildAlign deployment target: Check `deployment_target` in `react-native.config.js` and set Podfile platform to that version
- buildDisable Flipper temporarily: Comment out `:flipper_configuration` in Podfile to isolate the issue
A fix you cannot prove is a guess. Close the loop.
- verifiedRun `cd ios && pod install` exits with `Pod installation complete!` and no warnings
- verifiedOpen project in Xcode, build for a simulator (Product > Build) — should succeed
- verifiedRun `npx react-native run-ios` from project root — app launches on simulator
- verifiedRun `gem list cocoapods ffi` — both gems present and version numbers match expected
- verifiedRun `pod repo list` and confirm `trunk` shows recent dates (today or yesterday)
Things that make this bug worse or harder to find.
- warningUsing `sudo gem install` without `--user-install` — pollutes system Ruby and breaks later
- warningEditing `Podfile.lock` manually — it's auto-generated and will be overwritten
- warningRunning `pod install` from the project root instead of `ios/` directory
- warningDeleting `ios/Pods` without deintegrating first — leaves Xcode project references dangling
- warningIgnoring the Ruby version — macOS 12.3+ removed system Ruby, you must use a version manager
- warningRandomly updating all pods via `pod update` — can break pinned dependencies in your Podfile
The Flipper Fiasco: A Late-Night Pod Install Crash
Timeline
- 22:15`pod install` exits with `[!] Unable to find a specification for FlipperKit`
- 22:20Run `pod repo update` — takes 10 minutes, then same error
- 22:35Google the error — find a SO post suggesting to delete Podfile.lock and Pods
- 22:40`rm -rf ios/Pods ios/Podfile.lock && cd ios && pod install` — hangs for 5 minutes
- 22:50Kill pod install, run `gem list ffi` — ffi is missing
- 22:52`gem install ffi --user-install` — installs but pod install still hangs
- 23:00Check `ruby -v` → 2.6.8 (system Ruby). Install Ruby 3.2 via rbenv
- 23:15`gem install cocoapods ffi` in new Ruby, `pod install` completes in 30 seconds
- 23:20`npx react-native run-ios` — app builds and runs on simulator
It was 10 PM on a Friday, and I was prepping a build for the weekend release. I pulled the latest from main and ran `pod install` — immediate failure: `[!] Unable to find a specification for FlipperKit`. My heart sank. FlipperKit is a transitive dependency from React Native's Podfile, and I hadn't touched it. I assumed a stale repo. I ran `pod repo update`, waited ten minutes, got the same error. Classic.
I nuked the entire `ios/Pods` and `Podfile.lock` — a desperate move I've regretted before. `pod install` then hung indefinitely. I force-quit and checked my gem list. `ffi` was missing! That explained the hang — CocoaPods uses FFI to load native extensions. But installing `ffi` didn't fix it. Then I checked my Ruby version: 2.6.8, the ancient system Ruby. macOS Ventura shipped with a broken Ruby 2.6.8 that has path issues with native gems. I installed Ruby 3.2 via rbenv, reinstalled CocoaPods and FFI, and `pod install` ran clean in 30 seconds.
The root cause was a chain: system Ruby → broken FFI → CocoaPods can't load specs → FlipperKit spec not found. The lesson: never use macOS system Ruby for development. Always use a version manager. And never nuke your Pods directory before checking the Ruby version.
Root cause
macOS system Ruby 2.6.8 lacked a properly compiled `ffi` gem, causing CocoaPods to hang on spec resolution and fail to find FlipperKit.
The fix
Installed Ruby 3.2 via rbenv, installed cocoapods and ffi gems under the new Ruby, then ran `pod install`.
The lesson
Check your Ruby environment first. System Ruby is not your friend. Use rbenv or chruby with a modern Ruby (3.x) and always verify `gem list ffi` before debugging pod specs.
CocoaPods uses the `ffi` gem to load native shared libraries that are part of its dependency resolution. Without a working `ffi`, CocoaPods will either hang indefinitely (trying to load a native extension) or crash with a cryptic `LoadError`. macOS system Ruby (especially on Monterey and Ventura) ships with a version of Ruby that often lacks a compiled `ffi` native extension because of Apple's SIP (System Integrity Protection) and missing Xcode command line tools.
The fix is to install `ffi` with the `--user-install` flag or, better, use a version-managed Ruby. Run `gem install ffi --user-install` and verify with `ruby -e "require 'ffi'"` — if it returns nothing, FFI works. If it raises an error, your Ruby is broken. Switch to a version manager: `brew install rbenv`, then `rbenv install 3.2.2`, then `gem install cocoapods ffi`.
React Native 0.70+ requires a minimum iOS deployment target of 12.0 (or 11.0 for 0.69). If your Podfile has `platform :ios, '10.0'`, many podspecs (including React-Core) will fail to resolve because their `spec.platform` constraints conflict. The error might not say 'platform mismatch' — it may just say 'Unable to find a specification for React-Core'.
Always check your Podfile's platform line: `grep platform ios/Podfile`. It should match the `deployment_target` set in `react-native.config.js` (or the RN default). To fix: update the platform to at least `'12.0'` and run `pod install --repo-update`.
After repeated `pod install` failures, the local cache in `~/.cocoapods/repos/trunk` can become corrupted or stale. The symptom is often a spec that you know exists on the trunk repo but CocoaPods claims is missing. The nuclear option: `pod repo remove trunk && pod repo add trunk https://github.com/CocoaPods/Specs.git` — this forces a fresh clone of the entire spec repo (~500MB).
Alternatively, a lighter reset: `cd ios && pod deintegrate && pod cache clean --all && rm -rf Podfile.lock Pods && pod install --repo-update`. This clears the local Pods directory, the lock file, and forces CocoaPods to re-resolve all dependencies from the updated repo. This is my go-to when I suspect cache issues.
React Native's autolinking in the Podfile uses `use_frameworks!` to generate static libraries. Some third-party pods (especially those with Swift dependencies) require `use_frameworks! :linkage => :static`. If your Podfile has a plain `use_frameworks!` without options, you may get linker errors like `ld: framework not found Pods_...`.
The fix: change `use_frameworks!` to `use_frameworks! :linkage => :static` in your Podfile. Then run `pod deintegrate && pod install`. This is especially common with React Native 0.69+ and libraries like `react-native-reanimated` or `react-native-firebase`.
CocoaPods relies on `xcodebuild` to compile native extensions during `pod install`. If your selected Xcode version (via `xcode-select -p`) doesn't match the command line tools version, you'll get obscure build errors like `ld: library not found for -lPods-...` or `Invalid bitcode signature`. This happens often after Xcode updates.
Fix: Run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` to point to the correct Xcode. Then verify with `xcodebuild -version`. If you have multiple Xcode versions (e.g., Xcode 14.2 and 14.3 beta), make sure the selected one matches your target SDK.
Frequently asked questions
Why does `pod install` hang indefinitely on macOS Ventura?
Most likely the `ffi` gem is missing or miscompiled. macOS Ventura ships with Ruby 2.6.8 which lacks a properly built `ffi` native extension. Install FFI with `gem install ffi --user-install`. If that fails, install Ruby 3.2 via rbenv and reinstall both cocoapods and ffi.
Should I use `pod install` or `npx pod-install`?
Always use `npx pod-install` from the project root. The `npx pod-install` command runs `pod install` inside the `ios/` directory and also runs the React Native post-install script that updates podspecs and autolinking. Plain `pod install` from `ios/` works but may miss autolinking changes.
How do I fix `[!] Unable to find a specification for React-Core`?
This usually means your local CocoaPods spec repo is stale. Run `pod repo update` first. If that fails, remove and re-add the trunk repo: `pod repo remove trunk && pod repo add trunk https://github.com/CocoaPods/Specs.git`. Then `pod install --repo-update`. Also check your Podfile platform is iOS 12.0 or higher.
Why does `pod install` succeed but Xcode build fails with `No such module`?
This usually indicates a mismatch between the pod installation and the Xcode workspace. First, open the `.xcworkspace` file (not `.xcodeproj`). If you're using the right workspace, try `npx react-native start --reset-cache`, then `cd ios && pod deintegrate && pod install`. The module may be a Swift pod that needs `use_frameworks! :linkage => :static`.
Can I use `pod update` to fix dependency issues?
Avoid `pod update` unless you intentionally want to upgrade all pods. It changes the `Podfile.lock` and can introduce breaking changes. Instead, use `pod install --repo-update` which respects your Podfile constraints and only updates the spec index.