CocoaPods Missing? Fix macOS iOS Builds

You run flutter build ios and the terminal answers with CocoaPods not installed or invalid state. Android built fine minutes ago, your Dart code is untouched, and suddenly shipping to iPhones requires archaeology in Ruby gems, Xcode paths, and a specs repository you never chose to depend on. Every macOS Flutter developer meets this error — usually the morning Apple or Flutter updated something overnight.

The iOS build chain has more moving parts than Android's. Flutter generates an Xcode workspace, CocoaPods resolves native plugin dependencies into Pods, and xcodebuild compiles the result — with Ruby's gem environment, Homebrew's cellar, and Xcode's command-line selection all able to veto the process. Invalid state is the umbrella message for any veto: missing pod binary, ancient specs repo, Xcode pointing at nothing, license unaccepted.

This guide restores the chain in order. You will diagnose which link vetoed the build, install CocoaPods the right way for your Mac, aim xcode-select at a licensed Xcode, refresh the specs repo, and run the clean recovery sequence that rebuilds the workspace from scratch. By the end, iOS builds become a checklist instead of a curse.

Reading the Error: Four Vetoes, One Message

Invalid state is a summary, not a diagnosis — four different vetoes hide behind it. A missing binary prints pod: command not found or CocoaPods not installed and means PATH or installation is the problem. Stale specs produce version-resolution failures naming pods and versions that do exist upstream. Dangling Xcode selection surfaces as xcodebuild errors about developer directories that do not exist. License blocks mention accepting the Xcode license explicitly.

Match the log line before acting, because each veto's fix wastes time on the others. Reinstalling pods for a dangling xcode-select changes nothing; switching Xcode for a stale specs repo changes nothing. Read past Flutter's summary to the underlying tool's sentence — pod, xcodebuild, and gem each print their own verdict, and the true veto is the most specific line, not the loudest.

Reproduce in the failing shell, not a fresh one. CI shells, IDE embedded terminals, and login shells source different profiles, so a pod that works in your terminal can vanish in the build agent's PATH. Run which pod and echo PATH in the exact context that failed before concluding anything about installation state. Context is half the diagnosis on macOS.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/ios_env_probe.dart
// Reports the iOS toolchain links before you change any of them.
Future<void> main() async {
  if (!Platform.isMacOS) {
    stdout.writeln('iOS builds need macOS: run this probe on a Mac.');
    return;
  }
  for (final List<String> cmd in <List<String>>[
    <String>['which', 'pod'],
    <String>['pod', '--version'],
    <String>['xcode-select', '-p'],
  ]) {
    final ProcessResult r = await Process.run(cmd.first, cmd.sublist(1));
    stdout.writeln('\$ ${cmd.join(' ')} -> ${(r.stdout as String).trim()}${r.stderr}');
  }
}

Installing CocoaPods the Right Way per Mac

Two installers, one rule: prefer Homebrew on modern Macs. Brew install cocoapods lands the binary in the brew prefix with dependencies managed, surviving most Xcode updates untouched. Apple Silicon Macs should start here — brew's ARM bottles match the architecture and avoid the Rosetta gem tangle that plagued early M1 setups. Verify with pod --version in a fresh shell before touching the project.

Fall back to RubyGems where brew is unavailable, typically locked-down CI images: sudo gem install cocoapods, then confirm the gem binary directory sits on PATH. Gem installs couple to the system Ruby, so macOS Ruby upgrades can orphan the pod binary — the classic works-after-reboot failure. If you choose gems, document the Ruby version alongside and expect to reinstall pods tooling after major OS upgrades.

Never mix installers on one machine without cleanup. A brew pod shadowed by an older gem pod in PATH produces version confusion where pod --version and the build agent disagree. Pick one, uninstall the other, and record the choice in the project readme so the next engineer inherits a decision instead of a mystery. One installer, written down, ends an entire category of confusion for good.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/pod_install_check.dart
// Exits nonzero until exactly one healthy pod binary answers.
Future<void> main() async {
  if (!Platform.isMacOS) {
    stderr.writeln('Run on macOS: iOS toolchain checks need a Mac.');
    exit(2);
  }
  final ProcessResult which = await Process.run('which', <String>['pod']);
  final String path = (which.stdout as String).trim();
  if (which.exitCode != 0 || path.isEmpty) {
    stderr.writeln('No pod on PATH. Install: brew install cocoapods');
    exit(1);
  }
  final ProcessResult version = await Process.run('pod', <String>['--version']);
  stdout.writeln('pod at $path version ${(version.stdout as String).trim()}');
}

Aiming xcode-select at Licensed Xcode

Xcode-select is the pointer every Apple build tool follows: xcodebuild, simulators, and CocoaPods' own Xcode integration all resolve through it. macOS updates, Xcode renames, and fleet maintenance move the target without moving the pointer, leaving builds aimed at a directory that no longer exists. Sudo xcode-select -p prints the current aim — verify the path exists before believing any other diagnosis.

Repointing takes two commands with sudo. Sudo xcode-select --switch with the live Xcode.app developer path fixes the pointer; sudo xcodebuild -license accept clears the license gate that blocks headless builds after every major Xcode update. Both need admin rights, which is why fleet failures outnumber laptop failures — developers can sudo their laptops but wait on infra tickets for shared minis.

Confirm with flutter doctor, not hope. The Xcode toolchain section must show a version number and clean checkmarks; any error there vetoes the build no matter how healthy pods look. Re-run doctor after every Xcode update as a habit, and teach the fleet to do it automatically in preflight before a single pod command runs. Machines drift; preflights notice within minutes instead of days, every time.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/xcode_pointer_check.dart
// Fails fast when the Xcode pointer or license blocks headless builds.
Future<void> main() async {
  if (!Platform.isMacOS) {
    stderr.writeln('Run on macOS.');
    exit(2);
  }
  final ProcessResult sel = await Process.run('xcode-select', <String>['-p']);
  final String path = (sel.stdout as String).trim();
  stdout.writeln('Xcode path: $path');
  if (sel.exitCode != 0 || !Directory(path).existsSync()) {
    stderr.writeln('Dangling pointer: sudo xcode-select --switch <Xcode.app path>');
    exit(1);
  }
  final ProcessResult doc = await Process.run('flutter', <String>['doctor', '-v']);
  final String out = doc.stdout as String;
  final int i = out.indexOf('Xcode');
  stdout.writeln(i < 0 ? out : out.substring(i, i + 300));
}

Refreshing Specs and Reinstalling Pods Cleanly

The specs repository is CocoaPods' catalog of every pod version, and stale catalogs fail resolution with errors that blame your Podfile. Pod repo update refreshes the catalog — slow on the first run, routine after — and belongs before any reinstall attempt. Skipping it turns a five-minute refresh into an hour of dependency archaeology against metadata from 2021.

Reinstall deterministically once the catalog is fresh. Inside ios/, remove Pods and Podfile.lock together — the checkout and the lockfile are a pair, and deleting one without the other breeds half-resolved states. Pod install then resolves against fresh specs and writes a new lockfile; commit that lockfile so every machine and runner resolves identically. Uncommitted lockfiles are works-on-my-machine generators.

Read resolution output instead of scrolling past it. Modern CocoaPods names the disagreeing plugins and version constraints explicitly when pins conflict, turning version fights into editing tasks. When two plugins demand incompatible versions of a shared pod, the output tells you exactly which lines to renegotiate — upgrade one plugin, constrain the other, and rerun until resolution is boring. Boring resolution is the goal, not a side effect.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/pod_lockfile_guard.dart
// Reminds CI-friendly habits: lockfile committed, Pods regenerable.
Future<void> main() async {
  final File lock = File('ios/Podfile.lock');
  if (!lock.existsSync()) {
    stderr.writeln('ios/Podfile.lock missing: run pod install in ios/ and commit it.');
    exit(1);
  }
  final String text = await lock.readAsString();
  final int pods = RegExp(r'^  - ', multiLine: true).allMatches(text).length;
  stdout.writeln('Podfile.lock present with $pods pod entries.');
  if (Directory('ios/Pods').existsSync()) {
    stdout.writeln('ios/Pods checkout exists: safe to nuke and reinstall when stale.');
  }
}

The Full Recovery Sequence That Never Fails

When layers of staleness stack, reset them in dependency order. Flutter clean drops build outputs compiled against old pods. Flutter pub get regenerates plugin registrants so the Podfile reflects current plugins. Inside ios/, removing Pods and Podfile.lock discards the old resolution. Pod install rebuilds the checkout and workspace from fresh specs. Flutter build ios with no-codesign proves the workspace compiles without entangling signing identities.

Run the sequence verbatim rather than improvising subsets. Skipping pub get leaves registrants pointing at removed plugins; skipping the lockfile deletion preserves the stale resolution you are trying to escape; code-signing during recovery confounds toolchain errors with certificate errors. The no-codesign flag isolates the question to compilation — sign later, once the workspace provably builds.

Open Runner.xcworkspace, never Runner.xcodeproj, when verifying in the IDE. The project file lacks the Pods integration and fails with missing-header errors that send engineers back to reinstalling. The workspace is the buildable unit; the project is just one shelf of it. Confirm Pods listed in the navigator before declaring recovery complete.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/ios_recovery.dart
// Executes the ordered recovery sequence (needs network + Xcode).
Future<void> main() async {
  final List<List<String>> steps = <List<String>>[
    <String>['flutter', 'clean'],
    <String>['flutter', 'pub', 'get'],
    <String>['pod', 'repo', 'update'],
    <String>['flutter', 'build', 'ios', '--no-codesign'],
  ];
  for (final List<String> s in steps) {
    stdout.writeln('\$ ${s.join(' ')}');
    final ProcessResult r = await Process.run(s.first, s.sublist(1));
    stdout.write(r.stdout);
    if (r.exitCode != 0) {
      stderr.write(r.stderr);
      exit(r.exitCode);
    }
  }
  stdout.writeln('Recovery sequence complete.');
}

Keeping iOS Builds Green After Recovery

Recovery without guardrails is a loan against the next outage. Pin the fleet Xcode version in infrastructure config so overnight maintenance cannot silently move the toolchain again. Print the environment preflight — Xcode path, pod version, doctor output — on every CI job so drift announces itself in the first red log, not the thirtieth. Review Podfile and lockfile diffs with the same seriousness as Dart code, since they control the native half of the app.

Schedule the boring maintenance. Monthly pod repo updates keep resolution metadata warm; quarterly Ruby and CocoaPods upgrades stay ahead of deprecations; post-update doctor runs catch pointer drift the same day. Each task takes minutes on a schedule and hours as an incident — the math never favors deferral.

Document the Mac-specific choices where the next hire will find them. Installer choice, Xcode path conventions, license acceptance steps, and the recovery command belong in the project readme, not in one engineer's memory. Teams that write this down onboard iOS-capable developers in days; teams that do not spend each hire's first week rediscovering the screwdriver. Write it down once and every onboarding gets faster from day one.