Flutter iOS 'CocoaPods Did Not Set the Base Configuration': The Fix That Survives Xcode Upgrades

You updated Xcode. That is the whole trigger. You did not touch the Podfile, you did not change a dependency, you just let the App Store nag you into the latest Xcode, opened your Flutter project, ran flutter run on the simulator, and now every build prints a warning that sounds like it should be fatal but is not quite, and your Debug build is using Release settings or your app cannot find its pods at link time.

The warning is CocoaPods telling you it tried to wire itself into your Xcode project's build settings and found a config already sitting in the slot it needed. So it backed off and did nothing, rather than overwrite your config. The result is a project where the pods are installed on disk but not actually connected to the build.

The fix that every old answer gives you is "add an #include line to your xcconfig files". That is the right idea, but the exact line and the exact file path have drifted across Flutter and CocoaPods versions, so a fix copied from a 2022 answer often points at a path that no longer exists in the current template. Here is the version that survives Xcode upgrades, plus how to tell whether you even have the real problem or just a stale build folder pretending to be one.

The exact warning

[!] CocoaPods did not set the base configuration of your project because
your project already has a custom config set. In order for CocoaPods
integration to work at all, please either set the base configurations of
the target `Runner` to `Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig`
or include the `Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig`
in your build configuration (`Flutter/Debug.xcconfig`).

Read that last clause carefully, because it is the actual instruction and everyone skims past it: include the Pods xcconfig in your Flutter/Debug.xcconfig. CocoaPods is not asking you to click anything in Xcode. It is telling you which file it wanted to edit and could not.

Why an Xcode upgrade sets this off

A Flutter iOS project has two layers of build configuration that have to nest correctly.

At the top, Xcode assigns a base configuration file (an xcconfig) to each build configuration of the Runner target: one for Debug, one for Release, one for Profile. In a Flutter project those slots point at ios/Flutter/Debug.xcconfig, Release.xcconfig and generated Flutter settings.

CocoaPods, when you run pod install, generates its own xcconfig files under ios/Pods/Target Support Files/Pods-Runner/ that carry every header search path, framework search path and linker flag your pods need. For the build to see them, that Pods xcconfig has to be pulled into the base configuration Xcode is already using. CocoaPods does this by chaining: your Flutter/Debug.xcconfig uses an #include to pull in the Pods one.

Here is the collision. CocoaPods will only auto-set the base configuration slot if it is empty or already points at CocoaPods. In a Flutter project the slot is not empty; it points at Flutter's own xcconfig. So CocoaPods refuses to overwrite it and prints the warning, trusting that the #include line inside Flutter/Debug.xcconfig does the chaining instead. That line is normally there. An Xcode major upgrade, a flutter create over an existing project, a merge conflict on the ios folder, or a plugin migration can regenerate or clobber those files without the #include, and now the chain is broken. The pods are on disk, the build cannot see them.

The fix that survives upgrades

Step 1: Open the two xcconfig files and check the first line

Look at ios/Flutter/Debug.xcconfig. It should read exactly like this, with the Pods include as the first line:

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include? "Generated.xcconfig"
#include "Generated.xcconfig"

And ios/Flutter/Release.xcconfig:

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include? "Generated.xcconfig"
#include "Generated.xcconfig"

Two things matter here. First, order: in an xcconfig, a later #include and later assignments win, so the Pods line goes first and your Flutter and project settings can override on top of it. If the Pods include is at the bottom, it can clobber settings the build expects to win. Second, the path is relative to the ios/ directory, so it is Pods/Target Support Files/... with no leading ./ and no $(SRCROOT). That exact path is what the current Flutter template uses; older answers that write $(SRCROOT)/Pods/... or a different casing are the ones that stop matching.

If you also build the Profile configuration, there is a Pods-Runner.profile.xcconfig and the same include belongs in whichever xcconfig backs your Profile config.

Step 2: Confirm the base configuration slot in Xcode still points at Flutter's file

Open ios/Runner.xcworkspace (the workspace, never the bare .xcodeproj), select the Runner project, go to Info, Configurations, and expand Debug, Release and Profile. Each should show the Runner target using Flutter/Debug.xcconfig (or the matching one). If a stray migration left one pointing directly at a Pods xcconfig, set it back to the Flutter file. The chain is Xcode base config, then Flutter xcconfig, then the Pods include inside it.

Step 3: Clean and reinstall the pods

An Xcode major bump frequently leaves a stale Pods/ folder and lockfile that no longer match. Reset them cleanly:

flutter clean
cd ios
pod deintegrate
pod install --repo-update
cd ..
flutter pub get

pod deintegrate strips CocoaPods back out of the project so pod install can wire it in fresh; this is what fixes the case where the xcconfig looked right but the project's internal references had rotted. Expect pod install to finish with Pod installation complete and, if step 1 was already correct, without the base-configuration warning.

Step 4: Remove any old manual code-signing workaround from the Podfile

Since Flutter 3.3.3, CocoaPods no longer re-signs transitive dependencies, and Flutter's default Podfile no longer needs the old manual signing loop that people pasted into post_install years ago. If your Podfile still carries a hand-written block that force-sets CODE_SIGNING_ALLOWED or iterates targets to re-sign frameworks, it is now fighting the toolchain. Compare your ios/Podfile against a freshly generated one and delete workarounds you no longer recognise; a lingering signing hack is a common reason the build still misbehaves after the xcconfig is correct.

Verifying it is actually fixed

Run a clean build and watch for the warning to be gone:

flutter build ios --debug --no-codesign

A successful run does not print the "did not set the base configuration" warning, and it does not fail on a missing header or an undefined symbol from a pod. To prove the config is actually being applied rather than merely present, dump the resolved build settings and grep for a pod's search path:

cd ios
xcodebuild -workspace Runner.xcworkspace -scheme Runner \
  -configuration Debug -showBuildSettings | grep -i pods

If HEADER_SEARCH_PATHS or FRAMEWORK_SEARCH_PATHS contains a Pods path, the Pods xcconfig is being included and the chain is intact. If those come back with no Pods entries, the include is still not wired in and you are looking at the wrong xcconfig or the wrong configuration.

What people get wrong

Setting the base configuration to the Pods file directly in Xcode. The warning literally offers this as one option, and it makes the warning go away, but it breaks the other direction: now the Pods config is the base and Flutter's own settings are no longer chained in above it, so you trade a pod-linking problem for a Flutter-settings problem. The supported layout is Flutter's xcconfig as the base, including the Pods one. Keep it that way.

Copying an #include path from an old answer verbatim. This is the trap the whole article is about. The path, the casing and whether it uses $(SRCROOT) have all shifted. Do not paste a 2021 line; open a project created with your current Flutter version, copy the exact line it generates, and use that.

Deleting the ios folder and running flutter create . to regenerate it. This nukes every bit of native config you added: URL schemes, entitlements, Info.plist keys, signing settings, native plugins hooked up by hand. It sometimes fixes the warning and always costs you a day rediscovering what you lost. Fix the two include lines instead; that is the entire problem.

Ignoring it because "it still builds". Sometimes the build limps along using cached artefacts and you convince yourself it is cosmetic. Then CI, which starts from a clean checkout with no cache, fails on the exact same project, and now you are debugging under a deadline. A broken config chain is not cosmetic; it is a build that only works because of state you cannot reproduce.

When it is still broken

• pod install itself errors with "CocoaPods is installed but broken" or a Ruby load error. Your system Ruby was upgraded (a macOS update or a Homebrew bump) but the CocoaPods gem was not reinstalled under the new Ruby, so its native extensions no longer match. Reinstall it: sudo gem install cocoapods, or if you manage Ruby with rbenv, reinstall the gem in the current Ruby and run pod setup. Verify with pod --version.
• The warning is gone but a specific pod still will not link. Check the deployment target. A pod that requires iOS 13 while your Podfile pins platform :ios, '12.0' will install and then fail to link. Raise the platform line in the Podfile and re-run pod install.
• Everything is correct locally but CI fails. CI does not carry your local Pods/ folder or DerivedData. Make sure your pipeline runs flutter pub get then pod install from a clean state, and that ios/Flutter/Debug.xcconfig and Release.xcconfig are committed to git with the include lines intact. The Pods/ folder itself is usually gitignored, which is correct; the xcconfig files are not.
• You are chasing a store-side rejection, not a build error. That is a different problem. If your build succeeds locally but the upload is rejected, my write-up on Guideline 2.3.1 rejections is the one you want.

The durable takeaway: this error is never really about the pods. It is about one include line that connects two config files, and an Xcode upgrade is just the event that most often disturbs it. Fix the line, keep the chain in the supported order, and the next Xcode update will not resurrect it.