Fix: Xcode Build Failed - Common Causes and Solutions

The Error

You hit Build (or press Cmd + B) in Xcode and get a red banner:

Build Failed

The Issue Navigator fills with errors like:

Build input file cannot be found: '/path/to/file.swift'

No such module 'SomeFramework'

Code signing "MyApp" failed

Swift Compiler Error: Cannot convert value of type 'X' to expected argument type 'Y'

Or the build just silently fails with no useful output at all. The project compiled fine yesterday, and now nothing works.

Xcode build failures have dozens of root causes. This guide walks through the eight most common ones, starting with the quickest fixes and working toward deeper issues.

Why This Happens

Xcode builds involve multiple subsystems: the Swift/Objective-C compiler, the linker, the code signing engine, dependency managers (CocoaPods, SPM), and the build system itself. A failure in any of these stops the entire build.

The most frequent triggers:

• Stale caches in the build folder or DerivedData that conflict with current source code.
• Provisioning profile or code signing misconfiguration, especially after certificate renewal or team changes.
• Swift version mismatches between your project, its targets, and third-party dependencies.
• Dependency manager state getting out of sync with your lockfile or Xcode project.
• Architecture mismatches when building for Apple Silicon (arm64) vs. Intel (x86_64) or simulator vs. device.
• Missing frameworks or libraries due to incorrect search paths or broken references.

Each fix below targets one of these root causes.

Fix 1: Clean Build Folder

The fastest fix for unexplained build failures is clearing Xcode’s cached build artifacts.

Go to Product > Clean Build Folder or press Cmd + Shift + K.

Then build again with Cmd + B.

If that does not resolve it, do a deeper clean. Close Xcode entirely, then delete the build directory from the terminal:

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

Replace YourProject with your actual project name prefix. Xcode appends a hash to the folder name, so the wildcard catches it.

If you want to nuke all DerivedData for every project:

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

Reopen Xcode and build. This forces a full recompile from scratch.

Why this works: Xcode’s incremental build system caches intermediate object files, module maps, and precompiled headers. When source files change in ways the build system does not detect (branch switches, rebases, manual file moves), these caches become stale and cause phantom errors.

Pro Tip: If you find yourself cleaning DerivedData frequently, add a shell alias for it. Put this in your ~/.zshrc:

alias xclean='rm -rf ~/Library/Developer/Xcode/DerivedData && echo "DerivedData cleared"'

Then just run xclean before your next build.

Fix 2: Delete Derived Data and Module Cache

Sometimes the module cache itself is corrupted, and even a clean build folder does not help. This goes one step further than Fix 1.

Close Xcode, then run:

rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf "$(getconf DARWIN_USER_CACHE_DIR)org.llvm.clang.$(whoami)/ModuleCache"

The first command removes all build artifacts. The second clears the Swift Package Manager cache. The third wipes the Clang module cache, which stores precompiled versions of framework headers.

After deleting these directories, open Xcode and let it re-index. The first build will be slower because everything recompiles from scratch, but stale cache issues will be gone.

If your project uses Swift Package Manager, also reset the package state:

xcodebuild -resolvePackageDependencies

Or in Xcode, go to File > Packages > Reset Package Caches.

This is especially relevant if you see errors about missing modules that you know are present in your Package.swift or Package.resolved. Similar dependency resolution issues can occur in other ecosystems too — if you work with Node.js projects, you may have encountered npm dependency tree errors which follow a similar pattern of cache invalidation fixes.

Fix 3: Fix Provisioning Profiles and Code Signing

Code signing failures are among the most confusing Xcode errors. They look like this:

Signing for "MyApp" requires a development team. Select a development team in the Signing & Capabilities editor.

No profiles for 'com.yourcompany.yourapp' were found

Provisioning profile "iOS Team Provisioning Profile: *" doesn't include signing certificate

Start by checking your signing configuration:

1. Select your project in the navigator.
2. Select your target.
3. Go to the Signing & Capabilities tab.
4. Make sure Automatically manage signing is checked.
5. Select the correct Team from the dropdown.

If automatic signing does not resolve it, the underlying certificates may be expired or revoked. Open Keychain Access and check for expired certificates:

1. Open Keychain Access (search Spotlight).
2. Select login keychain on the left.
3. Filter by My Certificates.
4. Look for any expired Apple Development or Apple Distribution certificates (they show a red X).
5. Delete expired certificates.

Then go back to Xcode, and under Xcode > Settings > Accounts, select your Apple ID and click Download Manual Profiles or Manage Certificates to regenerate them.

For CI/CD environments, you need to install certificates and profiles manually. Export your signing certificate as a .p12 file from Keychain Access, then import it on the build machine:

security import certificate.p12 -k ~/Library/Keychains/login.keychain-db -P "yourpassword" -T /usr/bin/codesign

If you are dealing with CI/CD build failures in general, the troubleshooting approach is similar to what you would follow for GitHub Actions exit code 1 errors — check environment variables, permissions, and signing assets.

Common mistakes with code signing:

• Changing the bundle identifier without updating the provisioning profile.
• Having multiple versions of the same certificate in Keychain (delete duplicates).
• Forgetting to add a new device’s UDID to the provisioning profile for ad-hoc distribution.

Fix 4: Resolve Swift Version Mismatches

Swift version conflicts cause errors like:

Module compiled with Swift 5.9 cannot be imported by the Swift 5.10 compiler

Compiling for iOS 15.0, but module 'SomeLib' has a minimum deployment target of iOS 16.0

Check which Swift version your project uses:

1. Select the project in the navigator.
2. Go to Build Settings.
3. Search for Swift Language Version (SWIFT_VERSION).
4. Verify all targets use the same Swift version.

You can also check from the command line:

xcrun swift --version

If a third-party library was compiled with a different Swift version, you need to either:

• Update the library to a version compatible with your Swift version.
• Change your project’s Swift version to match the library (not recommended unless necessary).
• Rebuild the library from source with your current toolchain.

For CocoaPods projects, set the Swift version in your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.10'
    end
  end
end

Then run:

pod install

For SPM dependencies, Swift version compatibility is handled through the Package.swift manifest. If a package declares .swift-tools-version: 5.9 and you are on Xcode 16 with Swift 6.0, it should still compile unless the code uses deprecated or removed APIs.

If you are getting runtime crashes from Swift optionals after fixing build issues, check the guide on Swift fatal error when unwrapping nil for safe unwrapping patterns.

Fix 5: Fix CocoaPods Issues

CocoaPods-related build failures show up as:

No such module 'Alamofire'

framework not found Pods_MyApp

The sandbox is not in sync with the Podfile.lock

Start with a full reinstall of pods:

cd /path/to/your/project
rm -rf Pods
rm -rf Podfile.lock
pod install

Warning: Removing Podfile.lock resets all dependency versions to the latest allowed by your Podfile. If you need exact version reproducibility, keep a backup of the lockfile first.

If pod install itself fails, update CocoaPods:

sudo gem install cocoapods
pod repo update
pod install

On Apple Silicon Macs, you may need to run CocoaPods under Rosetta or with arch:

arch -x86_64 pod install

Or install the arm64-native version of the ffi gem:

sudo arch -arm64 gem install ffi
pod install

After installing pods, make sure you are opening the .xcworkspace file, not the .xcodeproj. This is a common mistake. CocoaPods generates the workspace to link your project with the Pods project. Opening the .xcodeproj directly skips the Pods project entirely.

Also verify your Podfile targets match your Xcode targets. If you renamed a target in Xcode but did not update the Podfile, CocoaPods will generate configurations for the old target name.

Common Mistake: After merging a branch that changed the Podfile, many developers forget to run pod install. If you see “sandbox not in sync” errors, this is almost always the cause. Make pod install part of your post-merge routine.

Fix 6: Fix Swift Package Manager (SPM) Issues

SPM failures typically look like:

Missing package product 'PackageName'

Package resolution failed

cannot find 'SomeType' in scope (from an SPM dependency)

Reset SPM caches and re-resolve:

1. In Xcode, go to File > Packages > Reset Package Caches.
2. Then go to File > Packages > Resolve Package Versions.

If that fails, manually clear the SPM state:

rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/org.swift.swiftpm
rm -rf .build
rm -rf YourProject.xcodeproj/project.xcworkspace/xcshareddata/swiftpm

Then reopen Xcode and let it resolve packages again.

For version conflicts, check your Package.resolved file. It is located at:

YourProject.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved

If two packages require incompatible versions of the same dependency, you need to either:

• Update one or both packages to versions that share a compatible dependency range.
• Fork the conflicting package and adjust its version requirement.
• Use .upToNextMajor or .upToNextMinor version ranges in your package dependencies to give SPM more flexibility.

SPM network failures can also block resolution. If you are behind a corporate proxy or VPN, make sure Git can reach GitHub:

git ls-remote https://github.com/Alamofire/Alamofire.git

If that times out, your network configuration is blocking SPM. Configure Git to use your proxy:

git config --global http.proxy http://proxy.example.com:8080

Fix 7: Fix Architecture Mismatches (arm64 / x86_64)

Architecture errors are common after Apple’s transition to Apple Silicon. They look like:

building for iOS Simulator, but linking in object file built for iOS, for architecture arm64

Could not find module 'SomeFramework' for target 'x86_64-apple-ios-simulator'

Undefined symbols for architecture arm64

The root cause is a mismatch between the architecture of your build target and the architectures included in a linked binary (framework or library).

For simulator builds on Apple Silicon Macs:

The iOS Simulator on Apple Silicon runs arm64, but older precompiled frameworks may only include x86_64 simulator slices. Add arm64 to the Excluded Architectures for simulator builds:

1. Select your project.
2. Go to Build Settings.
3. Search for Excluded Architectures (EXCLUDED_ARCHS).
4. For Debug configuration, set the value to arm64 only for the iOS Simulator SDK.

Or add it via your Podfile for CocoaPods projects:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
    end
  end
end

For XCFramework issues:

If you maintain or consume an XCFramework, ensure it includes slices for all required architectures. Check what is inside an XCFramework:

lipo -info /path/to/SomeFramework.framework/SomeFramework

A properly built XCFramework for distribution should contain:

• ios-arm64 — for physical devices
• ios-arm64_x86_64-simulator — for simulators on both Apple Silicon and Intel Macs

If a slice is missing, you need to rebuild the framework with the correct architectures or contact the library maintainer.

For Mac Catalyst builds:

Mac Catalyst introduces another architecture layer. If you are building a Catalyst app and getting architecture errors, make sure your dependencies support the mac-catalyst platform variant. Not all iOS frameworks work with Catalyst out of the box.

This kind of platform-specific build issue also appears in cross-platform tools. If you work with Flutter, the Flutter build failed guide covers similar CocoaPods and architecture problems on the iOS side.

Fix 8: Fix Missing Frameworks and Libraries

Missing framework errors look like:

No such module 'UIKit'  // (wrong platform)

No such module 'SomeThirdPartyLib'

ld: framework not found SomeFramework

Undefined symbol: _OBJC_CLASS_$_SomeClass

Check Framework Search Paths:

1. Select your target.
2. Go to Build Settings.
3. Search for Framework Search Paths (FRAMEWORK_SEARCH_PATHS).
4. Verify the paths point to where your frameworks actually exist on disk.

A common problem is having a relative path like $(PROJECT_DIR)/Frameworks but the Frameworks directory does not exist or the framework files were not copied there.

Check Linked Frameworks:

1. Select your target.
2. Go to General > Frameworks, Libraries, and Embedded Content.
3. Make sure all required frameworks are listed.
4. For dynamic frameworks, set Embed to Embed & Sign.
5. For static libraries, set Embed to Do Not Embed.

Fixing “No such module” for system frameworks:

If Xcode cannot find system frameworks like SwiftUI, Combine, or UIKit, the issue is usually one of:

• Wrong deployment target. SwiftUI requires iOS 13+. Check Build Settings > iOS Deployment Target.
• Wrong SDK. You are building a macOS target but importing an iOS-only framework like UIKit.
• Corrupted Xcode installation. Reinstall Xcode from the Mac App Store or developer.apple.com.

Fixing linker errors (Undefined symbols):

Linker errors mean the compiler found the header/module but the actual binary is missing. Check:

• The framework is in Link Binary With Libraries build phase.
• Other Linker Flags (OTHER_LDFLAGS) includes -framework SomeFramework if needed.
• For Objective-C categories in static libraries, add -ObjC to Other Linker Flags.

# Verify a framework contains the expected symbols
nm /path/to/SomeFramework.framework/SomeFramework | grep "SomeClass"

If symbols are missing, the framework was compiled without them. Rebuild from source or get the correct binary from the vendor.

For Gradle-based build systems on Android, linking and dependency issues follow a different pattern but with similar root causes. The Gradle build failed guide covers dependency resolution for that ecosystem.

Still Not Working?

If none of the fixes above resolved your build failure, try these less obvious approaches:

Restart Xcode and your Mac. Xcode’s SourceKit and build daemons can get into bad states. A full restart clears everything:

killall Xcode
killall com.apple.dt.SKAgent
killall IBAgent

Then reopen your project.

Check the full build log. The Issue Navigator only shows a summary. For the complete output, go to the Report Navigator (Cmd + 9), select the failed build, and expand each step. The actual compiler or linker invocation and its raw output are hidden behind the disclosure triangles. The real error is often buried several lines deep in a step that Xcode summarized as something generic.

Try building from the command line. This bypasses Xcode’s UI layer and often gives cleaner error messages:

xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 16' build 2>&1 | tee build.log

Search the resulting build.log for the first real error.

Check for circular dependencies. If target A depends on target B which depends on target A, the build system may fail in non-obvious ways. Review your target dependency graph in Build Phases > Dependencies.

Update Xcode. Some build failures are Xcode bugs that Apple patches in point releases. Check for updates in the Mac App Store or download the latest version from developer.apple.com.

Check your .gitignore. If critical files like project.pbxproj or Package.resolved were accidentally ignored, Xcode will fail with misleading errors after a fresh clone. Verify these files are tracked:

git ls-files --error-unmatch YourProject.xcodeproj/project.pbxproj

If that command fails, the file is not tracked. Add it and commit.

Examine scheme settings. Go to Product > Scheme > Edit Scheme. Make sure the Build action includes all necessary targets and they are in the correct order. Missing targets here cause “no such module” errors even when the module exists in the project.

If your build failure involves Git-related issues like missing files after a merge, the guide on fixing Git merge conflicts covers resolving file conflicts that can break Xcode project references.