Flutter CocoaPods Error: Common Causes and Fixes
Running flutter build ios, flutter run on an iOS device/simulator, or pod install inside the ios/ directory fails with a CocoaPods dependency error.
[!] CocoaPods could not find compatible versions for pod ...
The Problem
Running flutter build ios, flutter run on an iOS device/simulator, or pod install inside the ios/ directory fails with a CocoaPods dependency error.
Symptoms
- •Build fails during the 'Running pod install' step of a Flutter iOS build
- •Terminal shows [!] CocoaPods could not find compatible versions... or a similar resolution failure
- •Error may reference a specific pod, a deployment target mismatch, or a stale Podfile.lock
Why This Happens
- •CocoaPods itself is outdated relative to what the installed pods require
- •Two plugins/pods require incompatible versions of a shared dependency
- •The Podfile's platform :ios deployment target is lower than what a plugin requires
- •A stale Podfile.lock or Pods/ directory from before a Flutter/plugin upgrade
- •Xcode command line tools path is misconfigured, so CocoaPods can't find the right Xcode version
// quick fix
From the ios/ directory, run `pod deintegrate && pod install` to fully reset CocoaPods' state — this resolves the majority of dependency-resolution errors caused by stale lock files.
CocoaPods errors have a bad reputation for being cryptic, but the actual resolution logic underneath is fairly mechanical: two or more pods want incompatible versions of something, or your local CocoaPods installation is out of date relative to what a newer plugin expects. The error message genuinely tells you which pods conflict, most developers just don't read past the first few lines.
The deintegrate-and-reinstall fix works more often than it should, honestly, because a lot of these errors come from stale state left behind after a Flutter or plugin upgrade rather than from a real, unresolvable conflict. Before you start manually editing deployment targets or Podfiles, it's worth just clearing everything and letting CocoaPods resolve from scratch.
If that doesn't fix it, the deployment target mismatch is the next most likely cause. Plugins bump their minimum iOS version over time, and if your Podfile hasn't kept up, you'll see a resolution failure that looks unrelated to versioning at first glance.
How to Fix It
1. Update CocoaPods
2. Clean and reinstall pods
3. Raise the deployment target in the Podfile
4. Read the actual conflicting pod names in the error
// common mistakes
- ×Opening Runner.xcodeproj instead of Runner.xcworkspace after CocoaPods is involved
- ×Deleting Podfile.lock without running pod install afterward
- ×Ignoring the deployment target requirement stated in a plugin's own documentation
How to Verify the Fix
- 1.Run flutter clean, then flutter build ios (or flutter run) again
- 2.Confirm pod install completes without errors and generates a fresh Podfile.lock
- 3.Open ios/Runner.xcworkspace (not .xcodeproj) in Xcode and confirm it builds
Skip the boilerplate
Production-ready Flutter starter kit with Firebase Auth, Firestore, Cloud Functions, push notifications, and Clean Architecture — ship your app in days, not months.
Did this article save you time?
I write these for free. If it helped, a coffee keeps me going — and more articles coming.