Xcode「JITError: Runtime linking failure / Symbols not found」の原因と解決方法

SwiftUI Previewで「JITError: Runtime linking failure」「Symbols not found」が出る場合、Preview用プロセスが必要なSwiftシンボルを読み込めていません。まず不足シンボルが属するパッケージやフレームワークを特定し、Preview対象ターゲットまで依存関係が正しく届いているかを確認します。

代表的なエラー
発生しやすい条件
推奨する解決手順
代替策
確認方法
注意点
まとめ
参考資料

代表的なエラー

JITError: Runtime linking failure
Additional Link Time Errors:
Symbols not found:
  _$s...

通常ビルドが通っても、Previewは専用の実行環境でコードを動的に読み込みます。そのため、アプリ本体では偶然解決している推移的依存関係、静的ライブラリ、条件付きターゲット、異なるアーキテクチャのバイナリがPreviewでは不足シンボルとして表面化することがあります。

発生しやすい条件

Swift Packageを別のPackageやFramework経由で間接利用している
Preview対象ターゲットに必要なPackage Productが直接追加されていない
Package.swiftのtarget dependenciesに必要なproductがない
静的・動的ライブラリやXCFrameworkが混在している
Simulator向けsliceがないバイナリ依存関係を使っている
Package.resolvedやDerivedDataが、依存関係変更前の状態を保持している

推奨する解決手順

1. 不足シンボルの所属先を特定する

Previewの診断詳細を開き、最初の不足シンボルを確認します。Swiftのmangled symbolは次のように読めます。

xcrun swift-demangle '_$s...'

モジュール名が分かれば、そのモジュールを提供するPackage ProductまたはFrameworkを追跡できます。複数の不足シンボルがある場合も、最初に欠けたモジュールから直します。

2. 依存関係を正しいターゲットへ追加する

Xcodeプロジェクトでは、アプリまたはPreviewを含むFrameworkターゲットのGeneral > Frameworks, Libraries, and Embedded Content、およびBuild Phases > Link Binary With Librariesを確認します。Package Productを、実際にimportするターゲットへ追加してください。

Swift Package内部なら、importするtargetのdependenciesにproductを宣言します。

.target(
    name: "FeatureUI",
    dependencies: [
        .product(name: "Numerics", package: "swift-numerics")
    ]
)

上位のアプリが同じPackageを使っているだけでは、下位のFrameworkやPackage targetから利用できる保証にはなりません。依存するターゲット自身に宣言します。

3. Packageとバイナリの対応環境を確認する

Packageの最低OSバージョンとPreviewのSimulator OSが合っているか
XCFrameworkにios-arm64-simulatorまたは対応するSimulator sliceがあるか
異なるXcode／Swiftコンパイラで作られたバイナリを混在させていないか
同じライブラリを複数経路で追加していないか

バイナリのslice確認には次を利用できます。

lipo -info path/to/Binary
file path/to/Binary

4. 依存関係を再解決して再ビルドする

File > Packages > Resolve Package Versionsを実行する
Product > Clean Build Folderを実行する
Previewを閉じて再開する
まだ古い成果物が疑われる場合のみDerivedDataを削除する

キャッシュ削除だけで直った場合も、依存宣言の不足が再発しないかクリーン環境やCIで確認してください。

代替策

Preview専用のモック実装を用意し、外部SDKの初期化を避ける
バイナリSDKにSimulator sliceがなければ、提供元の対応版を使うかPreviewではスタブへ切り替える
Previewだけの問題かを確認するため、同じSimulatorでアプリを通常実行する
特定Xcode版だけで再現する場合は動作確認済み版で作業し、最新安定版でも再検証する

確認方法

通常のSimulatorビルドと実行が成功する
SwiftUI PreviewのDiagnosticsから不足シンボルが消える
DerivedDataがない状態でもPreviewを再生成できる
CIまたは別のMacでもPackage解決とビルドが成功する

注意点

-all_loadや-force_loadを無条件に追加すると、重複シンボルやバイナリ肥大化を招くことがあります。不足シンボルの所属先と依存宣言を確認してから、ライブラリ提供元が指定する場合だけ使用してください。

2026年9月16日時点で、Appleはこのエラー文全般に対する単一の修正版を示していません。Xcodeの不具合と断定せず、Packageグラフ、ターゲットへのリンク、Simulator sliceを順に確認する必要があります。

まとめ

このJITErrorは、Previewの実行時リンクに必要なコードが含まれていないことを示します。シンボルをdemangleして提供モジュールを特定し、利用するターゲットへPackage Productを明示的に追加します。その後、対応アーキテクチャとOS条件を確認し、依存関係を再解決して検証してください。