はじめに
2025年11月20日に正式リリースされたSpring Boot 4.0.0 で H2 データベースを使った開発環境を試しに構築した際、Spring Boot 3.5.x と同じ設定で H2 コンソール（/h2-console）にアクセスしようとしたところ、Whitelabel Error Page が表示されてしまいました。
解決はしたのですが、公式のSpring Boot 4.0 Migration Guide を確認しても、H2 データベースの設定に関する具体的な記載が見当たらず、原因の特定に時間がかかってしまいました。
本記事では、この問題の原因と対処法について、備忘録として記載しておきます。
結論
説明よりもやり方が知りたい方向けに、先に結論を述べておきます。
Spring Boot 4.0.0 で H2 コンソールを使用する場合、spring-boot-h2console モジュールを明示的に追加する必要がありました。
Maven
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-h2console</artifactId>
</dependency>
</dependencies>
Gradle
dependencies {
implementation 'org.springframework.boot:spring-boot-h2console'
}
詳細
1. モジュール化の背景
Spring Boot 4.0.0 では、新しいモジュール設計が採用され、従来の大きな JAR ファイルではなく、より小さく機能ごとに分割されたモジュールとして提供されるようになりました。
モジュール化の目的（公式見解）
Spring Bootは、公式ブログの「Why Modularize the Codebase?」セクションでモジュール化の目的を以下のように説明しています。
公式ブログより引用
Maintainability and architectural clarity: With smaller modules and enforced boundaries, the team and our contributors can reason about each domain more clearly. Module boundaries become contracts rather than soft conventions. Your IDE also offers a much more focused view of the world. No more code completion suggestions of classes you're never going to need, and only the configuration properties you're actually using show up in the IDE popups.
Reduced artifact sizes and footprint: Instead of shipping one large autoconfigure jar containing many features you might not use, your application only pulls in the relevant modules. This reduces classpath overhead, startup scan costs, and disk space.
Stronger signals and avoidance of accidental auto-configuration: Because modules are scoped, Spring Boot has a much stronger signal about the reason you've pulled in a dependency.
意訳
-
保守性とアーキテクチャの明確化
- モジュールが小さく分割され、それぞれの役割が明確になることで、開発者がコードを理解しやすくなる
- モジュール間の依存関係が厳密に管理され、不適切な参照を防ぐことができる
- IDE での開発体験が向上し、不要なクラスの補完候補や使用していない設定プロパティが表示されなくなる
-
成果物のサイズとリソース使用量の削減
- 使用しない機能を含む大きな jar ではなく、必要なモジュールのみを取り込む
- jar ファイルのサイズ、メモリ使用量、起動時間、ディスク容量が削減される
-
不要な自動設定の防止
- 必要な機能だけをモジュールとして追加するため、意図しない機能が自動で有効化されることを防げる
H2 コンソールが独立したモジュール（spring-boot-h2console）になったのも、この方針に基づいているようです。
注意: Spring Boot 4.0.0 では、H2 コンソール以外にも非推奨となった依存関係パッケージや、テスト用パッケージの分割など、多くの依存関係の変更があります。詳細については Spring Boot 4.0 Migration Guide を確認してください。
2. H2 コンソールの設定
公式リポジトリにおける変更の詳細
公式 GitHub リポジトリ上でのファイル配置を比較しました。
Spring Boot 3.5.x まで
-
spring-boot-autoconfigureパッケージ内にH2ConsoleAutoConfigurationが含まれていた - H2 データベース依存関係を追加するだけで H2 コンソールが自動で有効化された
spring-boot/spring-boot-project/spring-boot-autoconfigure/
└── src/main/java/org/springframework/boot/autoconfigure/h2/
├── H2ConsoleAutoConfiguration.java
├── H2ConsoleProperties.java
└── ...
Spring Boot 4.0.0 以降
-
H2ConsoleAutoConfigurationがspring-boot-autoconfigureから削除された - 新しい独立モジュール
spring-boot-h2consoleに移動された
spring-boot/module/spring-boot-h2console/
└── src/main/java/org/springframework/boot/h2console/autoconfigure/
├── H2ConsoleAutoConfiguration.java
├── H2ConsoleProperties.java
└── ...
必要な対応
H2 コンソールを使用する場合、spring-boot-h2console モジュールを明示的に追加する必要があります。
spring-boot-h2console モジュールは推移的依存関係として H2 データベース本体（com.h2database:h2）を含んでいるため、H2 データベース本体を別途追加する必要はありません。
尚、データベース本体とコンソール両方設定しても動くことは確認しています。
ただし、コンソールは利用せず、H2データベースを利用する場合は、com.h2databaseの設定を忘れないようにしましょう。
Maven
<dependencies>
<!-- H2コンソール（H2データベース本体を含む） -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-h2console</artifactId>
</dependency>
</dependencies>
Gradle
dependencies {
// H2コンソール（H2データベース本体を含む）
implementation 'org.springframework.boot:spring-boot-h2console'
}
application.properties の設定
H2 コンソールの設定は以下の通り、従来通りで問題ありません。
# H2 Console
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console
# H2 Database
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
まとめ
Spring Boot 4.0.0 で H2 コンソールを利用する場合、H2 コンソール用のモジュール（spring-boot-h2console）を明示的に追加する必要がある、ことがわかりました。
Spring Boot 4.0.0 では、H2 コンソール以外にもモジュールの細分化が行われています。クラスが見つからない系のエラーが発生した場合は、Spring Boot 4.0 Migration Guideを参照して、適宜必要なモジュールを追加していきましょう。