Framework Not Found Pods_Runner: Fixing It in Flutter iOS Builds

So you kicked off an iOS build and Xcode threw “framework not found Pods_Runner” right in your face. If you’re building through Devin Desktop, this one shows up more than you’d expect, usually right after a fresh clone or a dependency bump. I’ve hit this error enough times that I don’t even flinch anymore — I just go straight for the Podfile.

Quick Answer

If you just want the short version before the full explanation:

• Open Runner.xcworkspace, not Runner.xcodeproj — this alone fixes it about half the time
• Run pod deintegrate && pod install from the ios/ folder
• Delete ~/Library/Developer/Xcode/DerivedData and rebuild
• Confirm the Podfile targets match your actual Runner scheme name
• If building remotely (Devin Desktop, CI runners, etc.), check that the pod cache isn’t stale between sandbox sessions

If none of those land, keep reading — there’s more going on underneath.

Why It Fails

The Pods_Runner framework is generated by CocoaPods when it links your Flutter plugins into the iOS project. When Xcode can’t find it, it usually means one of three things happened somewhere between flutter pub get and the actual build step.

1. The workspace vs. project mismatch. This is the big one. CocoaPods builds Pods_Runner as part of Runner.xcworkspace. If Xcode (or a build script, or Devin Desktop’s own build wrapper) opens Runner.xcodeproj directly instead, the Pods framework simply isn’t part of that build graph. It’s not broken — it was never included in the first place.

2. Stale or partial pod install. And this one’s sneaky. If pod install gets interrupted — network hiccup, sandbox timeout, whatever — you can end up with a Podfile.lock that references pods that were never fully downloaded or linked. The build system sees references to Pods_Runner in the project file but the actual framework binary isn’t there.

3. DerivedData caching old build settings. Xcode caches build settings aggressively. So if you changed something in the Podfile (added a plugin, bumped a version, changed the platform target) but didn’t clear DerivedData, Xcode can be building against a memory of a project structure that no longer matches disk.

There’s a fourth cause that’s less common but real: mismatched CocoaPods versions between what generated the Podfile.lock and what’s installed in the build environment. Not 100% sure why this manifests as specifically a “framework not found” error rather than a version conflict warning, but I’ve seen it happen twice — both times on machines where CocoaPods had been auto-updated mid-project.

Common Scenarios

This error shows up in a few recognizable situations:

• Fresh clone of a Flutter repo on a new machine (or a fresh remote sandbox) where pod install hasn’t run yet
• After adding a new plugin to pubspec.yaml without following up with flutter pub get + pod install
• Building through an automated environment like Devin Desktop, where the build agent may open the project file instead of the workspace by default
• Switching Flutter or Xcode versions and rebuilding without clearing caches
• CI pipelines where the pod cache gets restored from a previous run that used a different Podfile

Technical Comparison Table

That table isn’t exhaustive. But it covers what I’ve actually run into, not theoretical edge cases pulled from a forum thread somewhere.

Step-by-Step Fixes

Step 1: Confirm you’re opening the workspace

Go into your ios/ folder and check. If you or your build tool are opening Runner.xcodeproj, that’s very likely your whole problem. Devin Desktop’s build config sometimes needs the workspace path set explicitly — check the build settings for the project rather than assuming it auto-detects this.

Step 2: Clean and reinstall pods

cd ios
pod deintegrate
rm -f Podfile.lock
pod install

This nukes the existing pod integration and rebuilds it from scratch. It’s a little heavy-handed, but it’s the fix that works most often in practice — more often than people expect, honestly.

Step 3: Clear DerivedData

rm -rf ~/Library/Developer/Xcode/DerivedData

Then rebuild. This step gets skipped a lot because it feels excessive, but stale build caches are a real source of this error, especially after switching Xcode versions.

Step 4: Rebuild from Flutter directly

flutter clean
flutter pub get
cd ios && pod install && cd ..
flutter build ios

Doing the full chain in order matters. Skipping flutter clean is one of those shortcuts that seems fine until it isn’t.

Step 5: Check your CocoaPods version

pod --version

Compare it against what’s specified (or implied) in your Podfile.lock. If there’s a mismatch, pin CocoaPods to a known-working version rather than letting it auto-update mid-project.

What Actually Worked For Me

Honestly, the first time I hit this, I assumed it was a plugin conflict and spent close to an hour ripping plugins out of pubspec.yaml one at a time to isolate it. That did nothing. Then I tried the classic flutter clean — also nothing, which surprised me a bit since that usually resolves half the weird build issues I run into.

What actually fixed it was almost embarrassingly simple: I was building through an automation flow that had cached the .xcodeproj path from an earlier project template, and it never got updated to point at the workspace. Found that out because a coworker asked “wait, are you sure it’s opening the workspace?” — a question I’d have answered “obviously” to if I hadn’t actually gone and checked. Turns out, not obviously.

So that’s the fix that solved it for me specifically, but I’ve also had the pod deintegrate route work clean on the first try for other projects. Your mileage may vary depending on which of the underlying causes you’re actually dealing with.

Advanced Fixes and Edge Cases

Checking the build log directly. If the standard fixes don’t work, open the full Xcode build log (not just the summary) and search for “Pods_Runner.framework” specifically. You’re looking for whether the build system ever attempts to copy or link it — if it’s not mentioned at all, that confirms a workspace/scheme problem rather than a missing-file problem.

Scheme mismatches. Less common, but if someone renamed the Runner target or duplicated a scheme, the Podfile’s target block can silently stop matching. Open the Podfile and confirm the target 'Runner' do block matches your actual target name in Xcode’s project navigator, not just what you assume it’s called.

Sandbox-specific pod cache issues. This is specific to remote or containerized build environments like Devin Desktop. If the pod cache directory persists between sessions but the underlying source checkout changes, you can get framework references that point to paths that no longer exist in that session’s filesystem. Clearing ~/Library/Caches/CocoaPods in addition to DerivedData sometimes resolves this when nothing else does.

Architecture mismatches on Apple Silicon. If you’re on an M-series Mac and pods were installed under Rosetta at some point, you can get framework linking errors that look similar to this one but stem from arch mismatches instead. Worth ruling out if you’re on a newer Mac and none of the standard fixes work.

Prevention Tips

• Always open .xcworkspace, never .xcodeproj, once CocoaPods is in the picture
• Run pod install immediately after any pubspec.yaml change that touches plugins
• Don’t let CocoaPods auto-update silently — pin the version in your project setup
• Clear DerivedData after major Xcode or Flutter version upgrades, not just when something breaks
• If you’re using an automated build agent (Devin Desktop or similar), verify its build path config points at the workspace, especially after any project restructuring

FAQ

Does this happen with Android builds too? No. This is an iOS-only, CocoaPods-specific error. Android’s build system doesn’t use Pods at all.

Will flutter clean alone fix it? Sometimes, but not reliably. It clears build artifacts but doesn’t touch CocoaPods’ own state, so if the root cause is pod-related, flutter clean alone won’t do much.

Is this related to a missing Podfile? It can be, if the ios/Podfile was deleted or never generated. Run flutter create . inside the project root to regenerate missing iOS scaffolding if that’s the case.

Why does this happen more in remote build environments? Because the build agent doesn’t always inherit the same assumptions a local Xcode install has about which file to open, and pod caches can persist across sessions in ways that don’t match the current checkout.

Can I just delete the Pods folder and reinstall? Yes, that’s basically what pod deintegrate plus reinstall does, just more thoroughly. Deleting the folder manually works too in most cases.

Editor’s Opinion

Honestly this error trips people up way more than it should for something with such a boring root cause. Ninety percent of the time it’s the workspace thing. I wish Xcode just warned you outright — “hey, you opened the wrong file” — instead of failing three build steps later with a message that sounds like something’s actually broken. It isn’t, usually. Check the workspace first, save yourself the hour I lost the first time.