Spring Boot 4への移行後にアプリが起動しない場合、最後に表示された例外だけを検索しても原因へ到達できないことがあります。JVMがクラスを読み込む前、設定データの準備中、ApplicationContextの生成中、Webサーバーの開始時、ApplicationRunnerの実行中では、確認すべきログと修正方法が異なります。最初に失敗段階を特定し、最初の原因例外とSpring Bootの診断メッセージを保存することが重要です。
移行作業では、依存ライブラリの世代不一致、変更された設定、Beanの自動構成条件、ポートやTLS、外部サービス接続などが同時に変わる可能性があります。本記事ではSpring Boot 4.1.2を基準に、FailureAnalyzer、Condition Evaluation Report、依存ツリー、設定とBean、Webサーバー、readinessを順番に調べ、修正を続けるか旧版へロールバックするかを判断する手順を整理します。

1. 起動失敗が起きた段階を特定する
1.1 Spring起動前の失敗を分ける
ログにSpring Bootのバナーや起動メッセージが出る前に停止する場合は、JVM、Javaバージョン、クラスパス、JAR、起動引数を確認します。UnsupportedClassVersionError、メインクラスが見つからない、JARが破損している、ネイティブライブラリを読み込めないといった問題は、ApplicationContextを調べても解決しません。
最初に実行した成果物とコマンドを固定します。IDEのRunではなく、本番と同じJARまたはコンテナイメージを使い、java -version、ファイルのハッシュ、イメージdigest、起動引数を記録します。
Spring Boot 4.1.2はJava 17以上を必要としますが、Javaの最低要件を満たすだけで、すべての利用ライブラリがそのJavaへ対応するとは限りません。社内ライブラリ、エージェント、JDBCドライバーなども確認します。
1.2 Environment準備中の失敗を確認する
設定ファイルの構文、Config Dataの場所、プロファイル、環境変数、必須プレースホルダーに問題があると、Bean定義を読み込む前に失敗します。ConfigDataResourceNotFoundException、YAML解析エラー、Could not resolve placeholderなどが手掛かりです。
使用しているapplication.ymlだけでなく、spring.config.import、外部ディレクトリ、ConfigMap、Secret、コマンドライン引数を確認します。ローカルではファイルが存在しても、コンテナへマウントされていない場合があります。
設定値そのものをログへ貼らず、設定元、キー名、読み込み順を記録します。秘密情報を調査チケットへ残さないことも重要です。
1.3 ApplicationContext以降の失敗を分類する
Bean生成中はBeanCreationException、UnsatisfiedDependencyException、NoSuchBeanDefinitionException、設定バインドではBindExceptionが出ます。Webサーバー開始時はポート、Servletコンテナ、SSL、Connector設定が原因になります。Runnerで失敗すると、Webサーバーが準備されたように見えてもApplicationReadyEventへ到達しません。
| 失敗段階 | 代表的な症状 | 主な確認対象 |
|---|---|---|
| JVM・クラスロード | UnsupportedClassVersion、ClassNotFound | Java、JAR、依存、起動コマンド |
| Environment | Config Data、YAML、placeholder | 設定ファイル、profile、外部設定 |
| Bean定義・生成 | BeanCreation、NoSuchBean | 自動構成条件、DI、設定バインド |
| Webサーバー | port in use、SSL、container | ポート、証明書、Servletコンテナ |
| Runner・初期化 | ApplicationRunner内の例外 | DB、外部API、初期データ、処理時間 |
| readiness前後 | 起動したがトラフィック不可 | health、readiness、ルーティング |
この分類を先に行うと、見るべきログと担当範囲を絞れます。
2. 再現条件と最初のログを保存する
2.1 同じ成果物と設定で再現する
調査中にコード、環境変数、依存バージョンを同時に変更すると、原因が分からなくなります。失敗したJARまたはイメージを保存し、設定の版、デプロイ時刻、コミット、Java、Spring Bootの版を対応させます。
コンテナでは、タグだけでなくdigestを記録します。latestや同じバージョンタグを上書きすると、同じ名前でも内容が変わり、再現できません。
外部サービスの状態も記録します。DB、メッセージブローカー、設定サーバー、DNS、証明書の問題は、アプリの変更なしでも起動結果を変えます。
2.2 ログを途中で切らずに取得する
例外の末尾だけをコピーせず、APPLICATION FAILED TO STARTの前後、最初のWARN・ERROR、例外チェーン全体を保存します。ログ集約基盤が行数や文字数を制限する場合は、元のコンテナログや標準エラーを取得します。
再起動ループでは、直前コンテナのログが必要です。新しいプロセスのログだけを見ると、最初の失敗が失われます。プラットフォームの再起動回数、終了コード、OOMKilledなどの状態も確認します。
ログレベルを上げる前の結果も残します。DEBUGを有効にすると大量のログでタイミングや見え方が変わるため、通常ログとDEBUGログを分けます。
2.3 一度に一つの仮説を検証する
依存追加、設定変更、Beanの削除を一度に行うと、どれが効いたか分かりません。「不足starter」「古い設定」「外部接続」のように仮説を一つ立て、最小変更で再実行します。
修正ごとに、変更内容、期待するログ変化、実際の結果を記録します。期待と違えば元へ戻し、次の仮説へ進みます。
動いた設定をそのまま採用するのではなく、なぜ必要だったかを確認します。たとえばlazy initializationで起動した場合、問題を解消したのではなく、Bean生成失敗をリクエスト時まで遅らせただけかもしれません。
3. FailureAnalyzerのメッセージを読む
3.1 DescriptionとActionを最初に確認する
Spring Bootは起動失敗時にFailureAnalyzerを実行し、対応できる例外についてDescriptionとActionを表示します。ポート競合、設定バインド、Bean競合などでは、長いスタックトレースより先に具体的な修正候補を得られます。
***************************
APPLICATION FAILED TO START
***************************
Description:
...
Action:
...
Actionは有力な手掛かりですが、アプリ固有の要件を考慮した最終判断ではありません。ポートを変える提案が出ても、本番のServiceやFirewallが固定ポートを前提にしていれば、占有プロセスを直す方が適切です。
3.2 最初の原因例外まで遡る
最上位のBeanCreationExceptionは、下位の例外を包んでいることがあります。Caused byを遡り、最初にアプリ固有コードまたは外部ライブラリが現れる箇所を探します。
NoSuchMethodErrorなら、呼び出し元が想定した版と実行時に選ばれた版が異なる可能性が高いです。ClassNotFoundExceptionなら、必要なモジュールがないか、パッケージが移動しています。BindExceptionなら、設定名、型、値を確認します。
例外クラスだけで検索せず、完全修飾クラス名、メソッド署名、Spring Bootと関連ライブラリの版を組み合わせます。同じ例外でも原因は複数あります。
3.3 独自FailureAnalyzerは繰り返す障害へ使う
社内starterや必須設定で同じ失敗が繰り返される場合は、独自FailureAnalyzerで理解しやすい説明を提供できます。例外を人間向けのFailureAnalysisへ変換し、対応手順を示します。
ただし、一般的な例外をすべて独自メッセージで覆うと、元の原因を隠します。対象例外を限定し、処理できない場合はnullを返して他のAnalyzerへ渡します。
診断メッセージへ秘密値を含めないことも重要です。設定キーや期待形式は示しても、実際のパスワードやトークンを表示しないようにします。
4. Condition Evaluation Reportで自動構成を調べる
4.1 debugを有効にして条件評価を出力する
FailureAnalyzerで原因が分からない場合は、--debugでCondition Evaluation Reportを表示します。
java -jar application.jar --debug
またはConditionEvaluationReportLoggingListenerのDEBUGログを有効にします。レポートには、どの自動構成が条件に一致したか、一致しなかったかが表示されます。
DEBUGはすべての問題を自動で説明する設定ではありません。ログ量が増えるため、対象環境と時間を限定し、秘密情報が出ていないか確認します。
4.2 PositiveとNegative Matchesを使い分ける
期待するBeanがない場合はNegative Matchesから、成立しなかった条件を探します。必要クラスがクラスパスにない、設定プロパティが無効、既存Beanがあるため自動構成がback offした、といった理由を確認できます。
想定外のBeanが作られた場合はPositive Matchesを確認します。どのクラスや設定が条件を成立させたか分かります。
レポートの全行を読むのではなく、対象技術名、AutoConfiguration名、Bean型で検索します。依存ツリーと組み合わせると、クラスパス条件と実際の導入元を対応させられます。
4.3 conditionsエンドポイントの適用範囲を理解する
Actuatorのconditionsエンドポイントでも条件評価をJSONで確認できます。ただし、アプリが起動できない状態ではエンドポイントへアクセスできません。
ローカルでは起動するが本番相当環境で機能が欠ける場合や、段階リリース中の新インスタンスを調べる用途に向きます。公開範囲と認証を適切に設定し、インターネットへ無制限に公開しないでください。
起動前の失敗にはログ出力、起動後の構成差にはActuatorというように使い分けます。
5. 依存関係と互換性を確認する
5.1 ClassNotFoundとNoClassDefFoundをstarterから調べる
クラス不足では、不足クラスを含むJARだけを直接追加する前に、Spring Boot 4で対応するstarterを確認します。モジュール再編により、3.5系で推移的に入っていたBoot側サポートが別starterへ移っている場合があります。
Mavenではdependency:tree、GradleではdependenciesとdependencyInsightを使い、実行時クラスパスを確認します。テストスコープにしかない依存や、optional依存を本番で利用していないかも見ます。
クラスのパッケージが変更された場合は、古いJARを追加するのではなくコードを新しいAPIへ移します。互換JARの追加は短期的に起動しても、同じ機能の新旧実装を混在させるおそれがあります。
5.2 NoSuchMethodErrorは版の不一致を疑う
NoSuchMethodErrorやAbstractMethodErrorは、コンパイル時と実行時のライブラリ版が異なるときに発生しやすいエラーです。呼び出し元JAR、対象クラスを持つJAR、実行時に選ばれた版を特定します。
Spring BootのBOMが管理する依存を個別に上書きしていないか確認します。Spring Framework、Jackson、Tomcat、Nettyなどを一部だけ別版にすると、公開APIが合わない場合があります。
社内starterがSpring Boot 3向けにビルドされたままの場合も注意します。Boot 3と4を同じ成果物で支える設計は内部APIやパッケージ変更の影響を受けやすいため、対応版を確認します。
5.3 依存差分を移行前後で比較する
3.5系と4.1.2で依存ツリーを保存し、追加、削除、版変更、導入経路変更を比較します。単純な行比較では順序や表示形式の差が多いため、groupId、artifactId、version、scopeへ正規化すると確認しやすくなります。
差分ごとに、Spring Boot管理、直接指定、社内BOM、プラグインのどれが決めた版か記録します。理由が説明できない直接バージョン指定は削除候補です。
脆弱性対応などで上書きが必要な場合は、Spring Bootの対応版、互換性テスト、解除条件を記録します。起動のために版を下げた状態を恒久化しないようにします。
6. 設定バインドとBean生成を切り分ける
6.1 BindExceptionはキー・型・値を確認する
設定バインド失敗では、対象@ConfigurationProperties、プロパティ名、値、期待型、PropertySourceを確認します。文字列からDuration、DataSize、列挙型、URLなどへの変換で失敗することがあります。
移行後に設定名が変わった場合、古いキーが無視され、新しい必須値が未設定になることがあります。設定ファイルだけでなく環境変数、Secret、デプロイ定義も検索します。
本番値をローカルへコピーする必要はありません。形式と存在条件を再現し、秘密値はダミーへ置き換えます。
6.2 Bean不足とBean競合を分ける
NoSuchBeanDefinitionExceptionは、依存モジュール不足、自動構成条件不成立、Component Scan範囲、profile、明示的除外を確認します。Condition Evaluation Reportで対象AutoConfigurationを探します。
NoUniqueBeanDefinitionExceptionは、同じ型のBeanが複数作られた状態です。旧互換モジュールと新モジュール、独自Beanと自動構成Beanが共存していないか確認します。
とりあえず@Primaryを付けると起動する場合がありますが、用途の異なるBeanを隠すだけかもしれません。Bean名、Qualifier、作成条件、利用先を整理します。
6.3 循環参照を無理に許可しない
依存関係の変更によってBean生成順が変わり、潜在していた循環参照が表面化することがあります。設定で循環参照を許可する前に、責任分割と依存方向を見直します。
コンストラクター注入の循環は設計上の問題を発見しやすい利点があります。イベント、インターフェース、サービス分割などで方向を整理します。
移行期限のため一時回避する場合は、対象Bean、理由、削除期限、回帰テストを記録します。恒久設定として残さないようにします。
7. Webサーバーと起動後処理を確認する
7.1 ポート・SSL・Servletコンテナを調べる
Port ... was already in useでは、使用プロセス、コンテナのポート割り当て、管理ポートを確認します。別ポートへ変えて起動できても、Serviceやロードバランサーの接続先と一致しなければ解決ではありません。
SSLでは、証明書パス、パスワード、形式、有効期限、秘密鍵、マウント権限を確認します。Bootの設定変更と基盤側のSecret更新を別々に確認します。
Spring Boot 4はServlet 6.1対応コンテナを前提とします。外部TomcatやWAR配備では、アプリだけでなく実行コンテナの世代も一致させます。
7.2 DBマイグレーションと外部接続を分ける
DataSource生成、Flyway・Liquibase、JPA初期化、初期データ投入のどこで失敗したか確認します。接続拒否とスキーマ不整合では、担当と戻し方が異なります。
外部サービス停止時にアプリ全体を起動失敗にする必要があるかも検討します。必須依存ならfail-fastが有効ですが、任意機能なら起動後に利用不可として扱う設計もあります。
移行のためにDBマイグレーションを無効化して起動する場合、確認環境を限定します。本番でスキーマとコードの不一致を残す方法として使わないでください。
7.3 Runnerの例外と長時間処理を確認する
CommandLineRunnerやApplicationRunnerの例外は、ApplicationContextのrefresh後でもアプリ起動を失敗させます。初期データ、キャッシュ構築、外部API確認をRunnerで行っている場合はログを分けます。
長時間処理はreadiness到達を遅らせます。必須処理、非同期化できる処理、起動後に実施すべき処理を分けます。
@PostConstructへ重い処理を置くとBean生成失敗として見え、診断しにくくなります。起動タスクはRunnerなど目的が分かる場所へ置き、タイムアウトと失敗方針を決めます。
8. 起動成功とトラフィック受付を分ける
8.1 ApplicationReadyEventまで到達したか確認する
Webサーバーがポートを開いた時点と、アプリがリクエストを処理できる時点は同じではありません。Spring BootはContext refresh後にApplicationStartedEvent、Runner実行後にApplicationReadyEventを発行します。
ログにStarted ...があっても、その直後にRunnerで失敗してプロセスが終了する場合があります。プロセスの継続、終了コード、Readyイベント相当のログを確認します。
独自の準備処理がある場合は、readinessへ反映し、完了前にトラフィックを流さないようにします。
8.2 livenessとreadinessを混同しない
livenessは内部状態が回復不能か、readinessはトラフィックを受け付けられるかを示します。外部DB停止をlivenessへ含めると、多数のインスタンスが再起動して障害を拡大する可能性があります。
起動中や一時的な外部依存障害ではreadinessを下げ、ルーティングから外す設計を検討します。再起動で回復する内部破損だけをlivenessの対象にします。
プローブのパス、ポート、認証、初期遅延、タイムアウトがBoot 4移行後も一致しているか確認します。アプリが正常でもプローブ設定の不一致で再起動ループになることがあります。
8.3 スモークテストで業務境界を確認する
healthがUPでも、主要API、認証、DB、メッセージ処理が動くとは限りません。デプロイ後は、読み取り系の代表API、認証、主要な外部依存を小さなスモークテストで確認します。
書き込みテストはデータ影響を考慮し、専用テナントや後始末可能なデータを使います。金融・業務システムでは、二重実行や実取引を避ける設計が必要です。
スモークテストの失敗をログ、メトリクス、トレースへ紐付け、どのリリースのどのインスタンスか分かるようにします。
9. 修正継続かロールバックかを判断する
9.1 影響・時間・可逆性で判断する
ロールバックは「原因が分からないから戻す」だけではなく、利用者影響を止めるための制御です。影響範囲、許容停止時間、原因の特定度、修正の検証時間、データ変更の可逆性で判断します。
| 状況 | 基本判断 | 理由 |
|---|---|---|
| 新インスタンスだけ起動せず旧版が正常 | 新版を切り離して調査 | 利用者影響を抑えて再現できる |
| 全体停止し短時間で直せる設定ミス | 影響時間と手順で判断 | 即時修正が切戻しより安全な場合がある |
| 原因不明で影響が拡大 | 旧版へ戻す | 調査よりサービス回復を優先する |
| 非互換なDB変更を実行済み | 単純に戻さない | 旧コードが新スキーマを読めない可能性がある |
| セキュリティ・データ破損の疑い | トラフィック停止を含め判断 | 継続稼働が被害を増やす可能性がある |
判断権限と連絡先を事前に決めます。障害中に担当者を探す時間を減らします。
9.2 アプリとDBのロールバックを分ける
アプリイメージを旧版へ戻せても、DBスキーマ、メッセージ形式、キャッシュ、保存JSONが変更済みなら互換性を確認する必要があります。旧版が新版の書いたデータを読めるかを事前にテストします。
破壊的なスキーマ変更をアプリと同時に行うと、切戻しが難しくなります。追加、移行、切替、削除を段階化し、旧版と新版が共存できる期間を作ります。
ロールバック時にDBを過去時点へ戻すと、正常な取引や更新まで失う可能性があります。アプリ切戻しとデータ復旧を同じ操作として扱わないでください。
9.3 旧版成果物と設定を実際に使って戻す
ロールバックでは、検証済みの旧イメージdigest、対応する設定、Secret、デプロイ定義を使います。ソースから急いで再ビルドすると、以前と異なる依存が解決される可能性があります。
トラフィック切替、旧版の起動、readiness、主要スモークテスト、エラー率の回復までを一つの手順にします。切り戻しただけで監視を終了せず、遅延したメッセージや再試行処理を確認します。
原因調査用の失敗成果物とログは保存します。サービス回復後に再現し、修正と再リリースの条件を決めます。
10. 再リリースの完了条件を定める
10.1 根本原因と検出方法を記録する
「依存を追加したら直った」ではなく、どの条件が不足し、なぜ3.5系では動き、4.xで失敗したかを記録します。再現コマンド、最初の例外、依存または設定差分を残します。
同じ問題をCIで検出できるテストを追加します。少なくとも、最終成果物の起動、主要profile、主要外部設定のバインドを検証します。
原因が外部ライブラリの非互換なら、対応版、暫定回避、削除期限を管理します。
10.2 段階リリースで観測する
修正版は全台同時に置き換えず、可能なら一部インスタンスへ展開します。起動成功率、readiness到達時間、エラー率、レイテンシ、DB接続、メッセージ滞留を旧版と比較します。
観測期間は、起動直後だけでなく、定期処理やキャッシュ更新が実行される時間を含めます。起動に成功しても、後続処理で失敗する可能性があります。
しきい値を超えた場合の自動停止または手動判断を決めます。進行条件と停止条件を両方用意します。
10.3 完了チェックを実施する
次を満たした状態を移行完了とします。
- 採用するSpring Boot、Java、ビルドツール、主要依存の版が固定されている
- 全profileと本番相当設定で最終成果物が起動する
- FailureAnalyzerの警告とCondition Evaluation Reportの重要差分を確認した
- 不要なclassic・互換依存、暫定設定、直接バージョン指定を整理した
- readinessと主要スモークテストが成功する
- 段階リリースで旧版と比較し、エラー率と性能に問題がない
- ロールバック成果物、設定、手順が残っている
- 原因、修正、回帰テスト、再リリース判断を記録した
起動ログに例外がないだけでなく、トラフィックを安全に受け、問題発生時に戻せることまで確認します。
まとめ
Spring Boot 4移行後の起動失敗は、JVM・クラスロード、Environment、ApplicationContext、Webサーバー、Runner、readinessのどこで止まったかを最初に分類します。失敗した成果物と設定を保存し、通常ログ、FailureAnalyzerのDescriptionとAction、最初の原因例外を確認します。
自動構成が疑わしい場合は--debugまたはConditionEvaluationReportLoggingListenerで条件評価を確認し、依存ツリーと対応させます。ClassNotFound、NoSuchMethod、設定バインド、Bean不足・競合、ポート、SSL、外部接続を一度に変更せず、仮説ごとに検証します。
修正継続かロールバックかは、影響範囲、許容時間、原因の特定度、修正の検証時間、データ変更の可逆性で判断します。旧版イメージへ戻すだけでなく、DB・メッセージ・保存データとの互換性を確認し、段階リリースとスモークテストで再リリースを完了させます。
参考リンク
- Spring Boot Reference – SpringApplication Startup Failure
- Spring Boot How-to – Troubleshoot Auto-configuration
- Spring Boot Reference – Production-ready Features
- Spring Boot Reference – Endpoints and conditions
- Spring Boot Reference – Application Availability
- Spring Boot 4.0 Migration Guide
- Spring Boot 4.1.2 Documentation