fastlane gymでIPAの書き出しに失敗したら？2026年の切り分け
fastlane gymがエラーを返したとき、まずログからArchiveとIPA書き出しのどちらで止まったかを特定します。export_method、export_options、署名設定、実行環境を順に照合し、IPAの検収と次の対応を判断する方法を解説します。
目次
今週は、fastlane gymのログで失敗工程を特定してから、Archive、IPA書き出し、署名、成果物の順に確認してください。Archiveが完了しているなら、すぐにビルド設定を変えず、export_methodとexport_options、実際の署名資産が配布先に合っているかを先に照合します。
fastlaneでiOSアプリを自動ビルドしており、エラーが出た工程をまだ特定できていない独立開発者向けです。
遠隔Macや自前のCIでビルドを管理していて、環境差とプロジェクト設定を区別したい場合にも役立ちます。
App Store向けとAd Hoc向けの成果物を作る小規模チームは、配布先ごとの設定を見直せます。
fastlane gymの失敗位置をログで確定する
最初に見るのは、エラー出力の最後の行ではなく、失敗した処理を示す最初の有効なエラーです。fastlaneのgym（build_app）は、Xcodeのビルドと書き出しの処理を呼び出すため、Archiveの失敗と、その後のIPA書き出しの失敗を分けて判断します。fastlaneのgym公式ドキュメント
ログでは、次の工程を別々に確認してください。
- ビルド・Archive：プロジェクトやWorkspace、Scheme、ビルド設定、依存関係の解決、コンパイルが完了したかを確認します。
- IPA書き出し：Archive後に
exportArchiveが実行され、設定に沿って書き出せたかを確認します。Appleのコマンドラインからのアプリ書き出し手順では、アーカイブと書き出しが別の工程として説明されています。 - 成果物の検収・アップロード：IPAが所定の場所に生成されたか、その後のアップロードやApp Store Connectでの処理が完了したかを分けて確認します。
Archiveが成功しても、IPAが生成されたとは限りません。また、gymの書き出しが成功した後に起きたアップロード失敗や、App Store Connect側の処理待ちは、gymのIPA書き出しエラーとは別の問題です。
今週の調査では、失敗したログと実行コマンドを保存し、次の項目を上から確認すると、原因と対処を混同しにくくなります。
- [ ] ログからArchiveと
exportArchiveのどちらで処理が止まったかを特定する。 - [ ] laneに渡したプロジェクトまたはWorkspace、Scheme、ビルド設定が対象アプリと一致しているか確かめる。
- [ ] IPAの配布先を決め、その目的に合う
export_methodとexport_optionsか照合する。 - [ ] 自動署名か手動署名かを確認し、対象アプリとProvisioning Profileの組み合わせを調べる。
- [ ] ローカルと遠隔環境で、Xcode、fastlane、コマンドラインツール、作業ディレクトリ、署名資産の差を記録する。
- [ ] IPAの存在、アプリ識別子、署名、意図した配布方法を検収し、アップロード状態とは分けて記録する。
Archiveは成功したのにIPAを書き出せない場合、どこを見る？
exportArchiveで失敗しているなら、まず配布先と書き出し設定を照合します。export_methodやexport_optionsを変更する前に、TestFlight／App Store向け、Ad Hoc向けなど、作ろうとしているIPAの用途を明確にしてください。
fastlaneの設定例を古い記事からコピーすると、現在のfastlaneやXcodeで受け付けられる設定と合わない場合があります。設定項目の名前や指定方法は、使っているバージョンのfastlane gymドキュメントと、Appleのアプリ配布に関する説明で確認してください。
- TestFlight／App Store向け：テストやリリースの目的に合わせ、書き出し設定が現在のプロジェクトと一致しているか確認します。
- Ad Hoc向け：対象端末に配布する方法に合ったProvisioning Profileが選ばれているか確認します。AppleのAd Hoc Provisioning Profile作成条件も参照してください。
- その他の配布先：目的の方式が現在のXcodeとプロジェクトでサポートされているか、fastlaneとAppleの現行資料で個別に確かめます。
export_optionsを変えてもArchive工程の失敗は直りません。exportArchiveが実行される前に止まっているなら、Scheme、依存関係、コンパイルなどArchive側のログに戻ってください。
export_methodとexport_optionsはどう照合する？
export_methodは成果物の配布目的と一致させ、export_optionsはプロジェクトの署名設定やProfileの実態に合わせて確認します。両者を別々に設定してしまうと、選んだ配布方法と署名資産が食い違い、書き出しに失敗したり、意図しないIPAになったりする可能性があります。
署名は自動管理か手動管理かを先に把握しましょう。手動署名の場合は、アプリ識別子、Provisioning Profile、署名に使う証明書などが対象構成に合っているかを確認します。fastlaneのXcodeプロジェクト署名設定ガイドは、プロジェクト設定と署名を照合する際の基準になります。
一方、エラーの原因が署名情報そのものではなく、秘密情報を保管するリポジトリへの認証や取得にあるなら、gymの書き出しオプションだけを変更し続けないでください。その場合はfastlane matchの資料に沿って、署名資産の取得経路を別に調べます。
ローカルで成功するのに遠隔Macで失敗するのはなぜ？
ローカルと遠隔Macの結果が異なる場合は、マシン性能のせいと決めつけず、実行条件の差を一つずつ記録します。同じコミットでも、選ばれたXcode、コマンドラインツールの参照先、fastlaneの依存関係、作業ディレクトリ、署名資産の可視性が異なれば、実行結果が変わることがあります。
次のように比較し、変更は一度に一項目に絞ります。
xcodebuild -versionとxcode-select -pで、Xcodeのバージョンとコマンドラインツールの参照先を照合する。- fastlaneのバージョン、依存関係の固定状態、起動したlaneを比較する。
- 作業ディレクトリと、実際に選択されたWorkspaceまたはプロジェクト、Schemeを確かめる。
- 署名用の証明書やProfileが、遠隔環境のビルドプロセスから読み取れる状態か確認する。
- 同じコミットと設定で再実行し、差が消えたかを記録する。
Schemeの選択や動作が疑わしい場合は、XcodeのビルドScheme設定に関する説明を参照してください。遠隔Macの利用を検討する際は、VPSMACのMac利用案内で利用できる環境を確認できますが、環境を変えるだけで誤ったSchemeや署名設定が修正されるわけではありません。
出力IPAの配布方式と署名をどう確認する？
コマンドが終了したかだけで判断せず、指定した出力先にIPAがあることを確認し、そのIPAが想定したアプリと配布先に対応しているか検収します。IPAの生成、署名の妥当性、アップロードの成功、プラットフォーム側の処理完了は、それぞれ別の確認対象です。
プロジェクトのアプリ識別子と、IPAに含まれるアプリの識別子が一致するかを確認します。次に、選んだ配布方法に必要な署名とProfileが適用されているかを、プロジェクトの設定とAppleの配布要件に照らして調べてください。Ad Hoc向けなら、対象端末を含むProfileであることも確認が必要です。
IPAが作られていても、目的の配布方式でインストールや提出ができるとは限りません。ローカルの成果物検収を終えてからアップロードし、アップロード結果とApp Store Connectでの処理状態を別に追跡してください。
遠隔実行環境が原因なら、Macを使う期間も切り分ける
WindowsやLinuxで編集し、失敗するたびに別のビルド環境へソースや署名資産を渡す運用では、環境差を追う記録が分散し、署名情報の受け渡し箇所も増えます。CIの実行環境を共有する場合は、必要なタイミングにビルド枠を確保できないことも運用上の負担になります。
ただし、問題がSchemeやexport_optionsの誤りなら、Macを購入したりレンタルしたりしても解消しません。遠隔環境の差が原因だと確認できていて、リリース前の再現検証や継続的なビルドにmacOS環境が必要なら、物理Macを購入する代わりに、必要な期間だけVPSMACのMacを使う選択肢があります。利用条件はVPSMACのMac環境案内で確認し、まずXcodeとfastlane、署名資産、プロジェクトのビルド結果を自分の手順で検収してください。