xcodebuild stale DerivedData / module cache build failure in CI

A reused DerivedData directory or precompiled module cache from a different Xcode version or source state can produce errors like "PCH was compiled with module cache path ..." or phantom missing symbols. Clearing the cache restores a clean build.

What this error means

The build fails with module cache errors such as "module 'X' was built with an incompatible version", "PCH file ... not found", or unexplained errors that vanish after a clean build.

xcodebuild

error: module 'SomeKit' was built with an incompatible Swift compiler;
please rebuild the module or use a matching compiler
note: the module cache is at /Users/runner/Library/Developer/Xcode/DerivedData/.../ModuleCache.noindex

Common causes

Cached DerivedData from a different toolchain

A restored DerivedData cache was produced by a different Xcode/Swift version, so its precompiled modules are incompatible with the current build.

A corrupted clang module cache

An interrupted prior build left a partial ModuleCache, causing "incompatible" or "not found" errors on the next run.

How to fix it

Clean DerivedData and the module cache

Remove the DerivedData directory (or run xcodebuild clean).
Re-run the build so modules recompile against the current toolchain.
If you cache DerivedData, key the cache on the Xcode version.

Terminal

rm -rf ~/Library/Developer/Xcode/DerivedData
xcodebuild -scheme App clean build

Key any DerivedData cache on the toolchain

Include the Xcode version in the cache key so a toolchain change does not reuse incompatible modules.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/Library/Developer/Xcode/DerivedData
    key: dd-${{ env.XCODE_VERSION }}-${{ hashFiles('**/Podfile.lock') }}

How to prevent it

Include the Xcode version in any DerivedData cache key.
Run a clean build when switching Xcode versions.
Avoid sharing a module cache across incompatible toolchains.