Introduction

Xcode caches compiled module interfaces and precompiled headers in the DerivedData directory. When this cache becomes corrupted after dependency updates, Xcode version changes, or interrupted builds, you get persistent build failures that survive normal clean builds. The module cache contains stale compiled Swift module interfaces (.swiftmodule files) that no longer match the current source code.

Symptoms

  • No such module 'Alamofire' even though it is in the Package.swift
  • could not build Objective-C module for bridging header
  • Build fails with module compiled with Swift X.Y.Z cannot be imported by Swift A.B.C
  • Errors persist after Product > Clean Build Folder
  • Different errors on different machines for the same code
  • fatal error: module file was created by an older version of the compiler

Example error: `` error: failed to emit precompiled header for bridging header error: could not build Objective-C module 'MyApp' error: missing required module 'Firebase'

Common Causes

  • Swift toolchain version changed (Xcode update) without clearing cache
  • Swift Package Manager dependency updated but module cache not invalidated
  • Interrupted build leaving partial module artifacts
  • Multiple Xcode versions sharing the same DerivedData
  • Build settings changed without cache invalidation

Step-by-Step Fix

  1. 1.Delete DerivedData completely:
  2. 2.```bash
  3. 3.# Close Xcode first, then:
  4. 4.rm -rf ~/Library/Developer/Xcode/DerivedData

# Or use xcodebuild to find and delete xcodebuild clean -workspace MyApp.xcworkspace -scheme MyApp rm -rf ~/Library/Developer/Xcode/DerivedData/MyApp-* ```

  1. 1.Clean module cache specifically:
  2. 2.```bash
  3. 3.# Clear the module cache
  4. 4.rm -rf ~/Library/Developer/Xcode/DerivedData/**/ModuleCache*

# Also clear Swift package caches rm -rf ~/Library/Caches/org.swift.swiftpm rm -rf ~/.build ```

  1. 1.Resolve Swift Package dependencies:
  2. 2.```bash
  3. 3.# From project directory
  4. 4.rm -rf .build
  5. 5.swift package resolve
  6. 6.swift package update

# In Xcode: # File > Packages > Resolve Package Versions # File > Packages > Reset Package Caches ```

  1. 1.Fix build settings for module stability:
  2. 2.`
  3. 3.# In Xcode Build Settings:
  4. 4.# Set "Build Libraries for Distribution" to NO (unless building XCFramework)
  5. 5.# Set "Use Modern Build System" to YES
  6. 6.# Set "Enable Module Debugging" to YES (for debugging)
  7. 7.# Clear "Precompile Bridging Header" if causing issues
  8. 8.`
  9. 9.Nuclear option: complete clean:
  10. 10.```bash
  11. 11.# 1. Close Xcode
  12. 12.# 2. Delete all caches
  13. 13.rm -rf ~/Library/Developer/Xcode/DerivedData
  14. 14.rm -rf ~/Library/Caches/com.apple.dt.Xcode
  15. 15.rm -rf ~/Library/Caches/org.swift.swiftpm
  16. 16.rm -rf ~/.build

# 3. Reopen Xcode and rebuild ```

Prevention

  • Add a CI script that cleans DerivedData on Swift version changes
  • Use swift package reset when packages behave unexpectedly
  • Pin SPM dependency versions instead of using branch-based dependencies
  • Avoid sharing DerivedData across different Xcode versions
  • Add a build phase script that checks Swift version consistency
  • Use .xcconfig files to standardize build settings across the team