Flutter "CocoaPods not installed" (iOS) in CI

Building a Flutter iOS app runs CocoaPods to link plugin pods. When pod is missing or broken on the runner, Flutter stops with "CocoaPods not installed or not in valid state" before Xcode builds anything.

What this error means

A flutter build ios or flutter build ipa step fails with "Warning: CocoaPods not installed" and "CocoaPods not installed or not in valid state", with a hint to run sudo gem install cocoapods.

Flutter output

Warning: CocoaPods not installed. Skipping pod install.
CocoaPods is used to retrieve the iOS and macOS platform side's plugin code.
Error: CocoaPods not installed or not in valid state.

Common causes

No CocoaPods on the macOS runner

The image does not have the cocoapods gem installed, so pod is not on PATH.

A broken or outdated CocoaPods install

A partial or mismatched gem leaves pod present but unable to run, which Flutter reports as "not in valid state".

How to fix it

Install CocoaPods before the iOS build

Add a step that installs CocoaPods on the macOS runner.

.github/workflows/ci.yml

- run: sudo gem install cocoapods
- run: flutter build ios --no-codesign

Repair the pod repo and Flutter setup

Run pod setup to initialize the spec repo if it is missing.
Re-run flutter doctor to confirm CocoaPods is detected.
Re-run the build.

Terminal

pod setup && flutter doctor -v

How to prevent it

Install CocoaPods explicitly in CI rather than assuming it is present.
Cache the CocoaPods spec repo to speed up and stabilize installs.
Run flutter doctor in CI to catch a broken toolchain early.