Xcode「Module cache file not found」の解決方法

Xcodeでビルドすると「Module cache file not found」と表示され、コンパイルが停止することがあります。このエラーは、XcodeやClangが利用するモジュールキャッシュの参照先と実際のキャッシュ状態が一致しなくなった場合に発生しやすい問題です。DerivedDataの破損、Xcode更新後の古いキャッシュ、ビルド環境の切り替え、CI環境のキャッシュ復元などが主な原因です。

エラーの意味
代表的な発生状況
まず確認すること
解決方法1：Clean Build Folderを実行する
解決方法2：DerivedDataを削除する
解決方法3：ModuleCacheだけを削除する
解決方法4：Xcodeを終了してキャッシュを作り直す
解決方法5：Command Line Toolsの参照先を確認する
解決方法6：CocoaPodsを使用している場合
解決方法7：Swift Package Managerを使用している場合
CI環境で発生する場合
それでも直らない場合
注意点
まとめ

エラーの意味

代表的には次のようなメッセージが表示されます。

error: module cache file '/path/to/ModuleCache/...pcm' not found

XcodeはSwiftやObjective-Cのビルド時に、Clangモジュールを高速に読み込むためのキャッシュを作成します。このキャッシュ内のファイルが削除されたり、別のXcode・SDKで作成された古い参照だけが残ったりすると、存在しないキャッシュファイルを参照してビルドが失敗します。

代表的な発生状況

Xcodeを更新した直後
macOSやiOS SDKを更新した直後
DerivedDataを一部だけ削除した場合
ブランチ切り替え後にビルド設定や依存関係が大きく変わった場合
CocoaPodsやSwift Package Managerの依存関係を更新した場合
CIで古いModuleCacheやDerivedDataを復元した場合
複数バージョンのXcodeを切り替えて使用している場合

まず確認すること

Issue Navigatorで「Module cache file not found」の直前に表示されているパスを確認します。多くの場合、パスにはDerivedDataまたはModuleCache.noindexが含まれています。

~/Library/Developer/Xcode/DerivedData/.../ModuleCache.noindex/

次に、現在使用しているXcodeの場所を確認します。

xcode-select -p
xcodebuild -version

複数のXcodeをインストールしている場合は、意図したXcodeが選択されているか確認してください。

解決方法1：Clean Build Folderを実行する

Xcodeで「Product」→「Clean Build Folder」を実行してから再ビルドします。通常のCleanよりもビルド生成物を広く削除できるため、軽度のキャッシュ不整合ならこれだけで直ることがあります。

メニューに表示されない場合はOptionキーを押しながらProductメニューを開くと「Clean Build Folder」が表示されます。

解決方法2：DerivedDataを削除する

もっとも効果的な対処は、対象プロジェクトのDerivedDataを削除して再生成することです。Xcodeの「Settings」→「Locations」→「Derived Data」からフォルダを開き、対象プロジェクトのフォルダを削除します。

ターミナルからすべてのDerivedDataを削除する場合は次のコマンドを使用できます。

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

DerivedDataを削除すると次回ビルド時にインデックス作成や依存関係の再コンパイルが行われるため、初回ビルドに時間がかかることがあります。

解決方法3：ModuleCacheだけを削除する

DerivedData全体を削除したくない場合は、ModuleCacheを削除して再生成させる方法があります。

rm -rf ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex

環境によってはプロジェクトごとのDerivedData配下にModuleCacheが作られている場合もあります。エラーに表示されるパスを確認して対象キャッシュを削除してください。

解決方法4：Xcodeを終了してキャッシュを作り直す

Xcodeがキャッシュファイルを使用中のまま削除すると、古い参照が残る場合があります。Xcodeを完全に終了してからDerivedDataまたはModuleCacheを削除し、その後Xcodeを再起動してください。

解決方法5：Command Line Toolsの参照先を確認する

複数のXcodeを切り替えた直後に発生した場合、xcode-selectが別バージョンを指している可能性があります。

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

パスは実際に使用するXcodeの場所に合わせて変更してください。切り替え後は次のコマンドで確認します。

xcode-select -p
xcodebuild -version

解決方法6：CocoaPodsを使用している場合

Pods更新後に発生した場合は、DerivedDataを削除したうえでPodsを再インストールします。

pod deintegrate
pod install

その後、必ず.xcworkspaceを開いてビルドします。

解決方法7：Swift Package Managerを使用している場合

Package依存関係の変更後に発生した場合は、Xcodeの「File」→「Packages」からパッケージキャッシュをリセットし、依存関係を再解決します。必要に応じてDerivedDataも削除してください。

CI環境で発生する場合

CIでDerivedDataやModuleCacheをキャッシュしている場合、異なるXcodeバージョンやSDK間で同じキャッシュを共有しないことが重要です。キャッシュキーにXcodeバージョン、SDK、依存関係のロックファイルなどを含めます。

xcodebuild -version
xcrun --sdk iphoneos --show-sdk-version

ModuleCacheをCIキャッシュ対象から除外するだけで安定することもあります。

それでも直らない場合

次の順番で環境を切り分けます。

Xcodeを終了する
DerivedDataを削除する
Macを再起動する
依存関係を再取得する
xcode-selectの参照先を確認する
別の新規プロジェクトがビルドできるか確認する

新規プロジェクトでも同じエラーが出る場合は、特定プロジェクトではなくXcode環境やCommand Line Tools側の問題である可能性が高くなります。

注意点

エラーメッセージに表示された.pcmファイルだけを手動で作成したりコピーしたりする方法は推奨されません。モジュールキャッシュはXcodeとClangが環境に合わせて自動生成するため、キャッシュを削除して正しく再生成させる方が安全です。

まとめ

「Module cache file not found」は、多くの場合Xcodeのモジュールキャッシュと現在のビルド環境の不整合が原因です。まずClean Build Folderを試し、改善しなければDerivedDataまたはModuleCacheを削除してください。Xcodeを複数使っている場合はxcode-selectの参照先も確認します。CocoaPods、Swift Package Manager、CIを利用している場合は、依存関係や古いキャッシュが再利用されていないかも確認すると解決しやすくなります。