What this usually means
Flutter iOS builds fail because the toolchain has a broken dependency graph, misconfigured Xcode project settings, or environment inconsistencies. Most often it's a pod issue—either outdated CocoaPods, a plugin that hasn't been updated for the latest iOS SDK, or a conflict between Flutter's generated Podfile and manual edits. Second most common: Xcode version drift where the Swift compiler or minimum deployment target mismatches. Third: code signing, especially when switching between development and distribution certificates. The error messages are often misleading—'Swift compiler failed' might actually be a missing .swiftmodule from a pod.
The first ten minutes — establish facts before touching code.
- 1Run 'flutter clean && cd ios && pod deintegrate && pod install --repo-update && cd ..' — this resets the pod state completely.
- 2Open the workspace in Xcode and build with Cmd+B. Watch the full log (not just the error) for the first actual failure.
- 3Check the Runner target's Build Settings: 'Swift Language Version' should match the pods' requirement (usually 5).
- 4In Xcode, under 'Signing & Capabilities', verify the team and provisioning profile are valid for your device/entitlements.
- 5Run 'flutter doctor -v' and confirm Xcode, CocoaPods, and iOS versions are compatible. Look for '✗' or '!' in the output.
- 6Check the Podfile for any explicit 'use_frameworks!' or 'use_modular_headers!' that might conflict with Flutter's generated code.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchios/Podfile — check for manual edits that override Flutter's defaults.
- searchios/Runner.xcworkspace/xcshareddata/xcschemes/Runner.xcscheme — verify the build configuration.
- searchios/Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig — look for missing or empty FRAMEWORK_SEARCH_PATHS.
- searchBuild log in Xcode's Report Navigator (Cmd+9) — the real error is often 20 lines above the red stop sign.
- searchKeychain Access — verify the development certificate is present and not expired.
- search~/.cocoapods/repos — if 'pod repo update' fails, delete the master repo and re-setup with 'pod setup'.
Practical causes, not theory. These are the things you will actually find.
- warningCocoaPods version mismatch (1.10+ required for Flutter's generated Podfile).
- warningPlugin pod requires a minimum iOS version higher than Runner's deployment target (default 11.0).
- warningSwift language version mismatch between Runner target and a pod (e.g., pod uses Swift 4.2, Runner uses 5).
- warningCode signing identity not set to 'Automatically manage signing' or wrong team selected.
- warningMissing arm64 architecture in 'Excluded Architectures' when building for simulator on Apple Silicon Macs.
- warningCorrupted derived data — delete ~/Library/Developer/Xcode/DerivedData and rebuild.
Concrete fix directions. Pick the one that matches your root cause.
- buildSet iOS deployment target consistently: in Podfile, Runner target, and all plugin podspecs to 11.0 or higher.
- buildUse 'post_install' hook in Podfile to set Swift version: pod.target.build_configurations.each { |config| config.build_settings['SWIFT_VERSION'] = '5.0' }.
- buildFor Apple Silicon Macs, add 'arm64' to 'Excluded Architectures' only for the simulator build configuration.
- buildDelete Podfile.lock and run 'pod install --repo-update' to force re-resolution of dependencies.
- buildSwitch code signing to 'Automatically manage signing' and select a valid team. If using manual, ensure provisioning profile matches bundle ID.
- buildAs a last resort, use 'flutter build ios --no-codesign' to build without signing, then sign separately for distribution.
A fix you cannot prove is a guess. Close the loop.
- verifiedRun 'flutter build ios --debug' on a connected device — should complete without errors and install the app.
- verifiedOpen the built .xcarchive in Xcode Organizer and verify it can be exported for App Store Connect.
- verifiedRun the app on a simulator (iPhone 14 Pro, iOS 16.4) to confirm no linker or runtime errors.
- verifiedCheck the build log for 'BUILD SUCCEEDED' and zero warnings related to pods.
- verifiedVerify the app launches and all Flutter plugin functionalities work (e.g., camera, location).
Things that make this bug worse or harder to find.
- warningRunning 'pod install' without '--repo-update' when the error is about a missing pod version.
- warningManually editing the Podfile without understanding Flutter's automated section (//#< >#).
- warningChanging the Runner target's 'Build Settings' without checking the .xcconfig files Flutter generates.
- warningAssuming 'No such module' means the pod isn't installed — it often means the module's .swiftmodule is missing or architecture mismatch.
- warningIgnoring the first error in the build log — always scroll up to see the actual compile/link failure, not the cascade.
- warningUsing 'flutter run' without cleaning after switching between simulator and device builds.
Flutter iOS Build Failed on CI with 'Command CompileSwift failed'
Timeline
- 09:15CI build triggered after merging a PR that updated firebase_messaging to 14.0.0.
- 09:18Build fails with 'Command CompileSwift failed with a nonzero exit code' in Pods-Runner.
- 09:20Checked the full log — first error was 'No such module 'Firebase' in FirebaseMessaging plugin.
- 09:25Ran 'flutter clean && pod deintegrate && pod install --repo-update' locally — still failed.
- 09:30Noticed Podfile.lock had two different versions of Firebase/Core (9.6.0 and 10.0.0).
- 09:35Deleted Podfile.lock, ran 'pod install --repo-update', which resolved to Firebase 10.0.0 for all.
- 09:40Build succeeded locally but CI still failed — different Xcode version on CI (14.1 vs 14.2).
- 09:45Updated CI's Xcode to 14.2, re-ran build — green.
The PR looked clean — just a version bump for firebase_messaging. But when the CI build failed, I saw 'Command CompileSwift failed'. That's a generic wrapper; I opened the full log from the Report Navigator. The real error was deeper: FirebaseMessaging's Swift source file couldn't import Firebase. 'No such module' is almost always a pod dependency version conflict.
I reproduced locally and ran my standard reset: flutter clean, then in ios/ directory: pod deintegrate, pod install --repo-update. That often fixes stale pod caches. But this time it didn't. I checked Podfile.lock and saw two different Firebase/Core versions: 9.6.0 from an older plugin and 10.0.0 from firebase_messaging. The dependency graph was broken. I deleted Podfile.lock and ran pod install again — it resolved everything to 10.0.0. Local build passed.
But CI still failed. I checked the environment: CI had Xcode 14.1, I had 14.2. The Swift compiler in 14.1 didn't fully support some Swift 5.8 features in the new Firebase pod. Updated CI's Xcode to 14.2 and the build went green. Root cause: a stale Podfile.lock that allowed two Firebase versions, combined with a minor Xcode version mismatch. I added a CI step to always run 'pod install --repo-update' and pinned Xcode version in the CI config.
Root cause
Podfile.lock contained conflicting versions of Firebase/Core (9.6.0 and 10.0.0) causing 'No such module' during Swift compilation. Additionally, CI used Xcode 14.1 which didn't fully support Swift 5.8 used by Firebase 10.0.0.
The fix
Deleted Podfile.lock, ran 'pod install --repo-update' to unify Firebase version to 10.0.0. Updated CI Xcode to 14.2.
The lesson
Always blow away Podfile.lock when updating major plugin versions. Pin Xcode version across environments to avoid Swift compiler mismatches.
Flutter iOS builds are orchestrated by the 'flutter build ios' command, which delegates to Xcode's build system via the Runner.xcworkspace. The workspace contains the Runner project and all CocoaPods dependencies. The Podfile is auto-generated by Flutter (in the ios/ folder) and should not be manually edited except for the post_install hook or platform version.
Key files: ios/Podfile (defines dependencies), ios/Podfile.lock (exact resolved versions), ios/Runner.xcodeproj (project settings), and the xcconfig files in ios/Flutter/ (Flutter's build settings). When a build fails, the error often originates from a pod, not from Flutter itself. Always check the first error in the build log, which is usually a compile or link error in a pod.
The most common cause of "No such module" errors is a version conflict between two pods that depend on the same underlying module (e.g., Firebase/Core). CocoaPods resolves this by choosing the highest version, but if Podfile.lock is stale, it might hold onto an older version that doesn't expose the required module.
Solution: Delete Podfile.lock (or the entire ios/Pods folder) and run 'pod install --repo-update'. This forces CocoaPods to re-resolve all dependencies. If the conflict persists, check the podspecs in ios/Pods/Local Podspecs/ for any that pin an incompatible version. You can also run 'pod outdated' to see which pods have updates.
Flutter's default Runner target uses Swift 5.0. However, a pod might require Swift 4.2 or 5.5. If the Swift language version in the pod's target doesn't match Runner's, you'll get compile errors. The fix is to add a post_install hook in the Podfile that sets SWIFT_VERSION for all pods:
'post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.0' end end end'
This forces all pods to use Swift 5.0. If a pod truly requires a newer Swift version, you must update the pod or find an alternative. Also check that the Runner target's Swift Language Version is set to 5.0 in Xcode's Build Settings (under Swift Compiler - Language).
When building for the iOS simulator on an Apple Silicon Mac (M1, M2), Xcode tries to build for arm64 simulator, but many pods don't have an arm64 simulator slice. This causes linker errors: 'Undefined symbols for architecture arm64' or 'could not find module for architecture arm64'.
Fix: In the Runner target's Build Settings, add 'arm64' to 'Excluded Architectures' for the Debug and Release configurations (only for the simulator SDK). Alternatively, set 'EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64' in the Podfile's post_install hook. This instructs Xcode to build only for x86_64 simulator, which runs fine under Rosetta 2.
Code signing errors typically manifest as 'No signing certificate' or 'Provisioning profile not found'. Flutter's 'flutter build ios' automatically signs using the development team from the Runner target. If you're building for distribution (--release), you need a distribution certificate and provisioning profile.
Common pitfalls: using the wrong team (especially if you have multiple Apple accounts), expired certificates, or mismatched bundle ID. The quickest verification is to open the project in Xcode, go to Signing & Capabilities, check 'Automatically manage signing', and select the correct team. For CI, export a signing certificate and provisioning profile as .p12 and .mobileprovision files, and use the 'flutter build ios --export-options-plist' flag with a properly configured plist.
Frequently asked questions
Why does 'flutter build ios' succeed on my Mac but fail on CI?
Most likely environment differences: Xcode version, CocoaPods version, or Xcode command line tools. CI might have an older Xcode that doesn't support syntax used by newer pods. Also, CI might not have the correct code signing certificates. Check 'flutter doctor -v' on both environments and compare versions. Pin the Xcode version on CI using xcode-select.
What does 'No such module' mean exactly in the context of Flutter iOS build?
It means the Swift compiler cannot find the module declaration for a pod (e.g., 'import Firebase'). This usually happens when the pod is not installed correctly, or the module's .swiftmodule file is missing for the target architecture. Delete DerivedData, clean, and run pod install again. If the problem persists, check for version conflicts in Podfile.lock.
How do I fix 'Undefined symbols for architecture arm64'?
This is almost always a missing architecture slice. If you're building for simulator, add 'arm64' to 'Excluded Architectures' for the simulator configuration. If building for device, ensure the pod's binary contains arm64. For plugins, update to the latest version. You can also try 'use_frameworks!' in Podfile to force dynamic frameworks (which include all architectures).
Should I manually edit the Podfile for Flutter?
Only the post_install hook and the platform version (e.g., 'platform :ios, '11.0'') should be manually edited. The rest of the Podfile is auto-generated by Flutter and will be overwritten when you run 'flutter pub get' or 'pod install'. Do not add custom pod entries inside the Flutter-generated section; instead, use Flutter plugins.
How to fix code signing error 'No signing certificate'?
Open the Runner.xcworkspace in Xcode, go to the Runner target > Signing & Capabilities, check 'Automatically manage signing', and select your team from the dropdown. Xcode will create a development certificate if needed. For release builds, you need a distribution certificate and provisioning profile. Export them from Xcode Organizer and use them in your build command.