Spring Bootアプリ開発で頻発するWhitelabel Error Page｜Thymeleafのテンプレートエラーと対策まとめ

はじめに

Spring Bootを使用してWebアプリケーションを開発する際、「Whitelabel Error Page」 に遭遇したことがある方も多いのではないでしょうか？このエラーページは、Spring Bootのデフォルトのエラーページであり、主にビューのレンダリングに失敗した際や、例外が適切に処理されなかった場合に表示されます。

この記事では、特に Thymeleaf を使用している際に発生する「Whitelabel Error Page」の原因と、その対処法について詳しく解説していきます。

2. Whitelabel Error Pageとは？

2.1 エラーの概要

Spring Bootでは、デフォルトで「Whitelabel Error Page」と呼ばれるエラーページが提供されており、ビューのレンダリングに失敗した場合などに表示されます。

例えば、以下のようなページを見たことがあるかもしれません。

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.
There was an unexpected error (type=Internal Server Error, status=500).

このエラーページが表示される主な原因として、以下のようなケースが挙げられます。

Thymeleafのテンプレートが見つからない
Thymeleafの構文エラー
Controllerの設定ミス
アプリケーション内部で例外が発生している

3. よくある原因と解決策

3.1 Thymeleafのテンプレートが見つからない

原因: src/main/resources/templates/ 配下に対応するHTMLファイルが存在しない。

解決策

src/main/resources/templates/ 配下にテンプレートファイルがあるか確認する。
Controllerの@GetMappingで指定しているテンプレート名と、実際のファイル名が一致しているかチェックする。

@Controller
public class HomeController {
    @GetMapping("/home")
    public String home() {
        return "home";  // home.htmlが templates/ に存在する必要がある
    }
}

3.2 Thymeleafの構文エラー

原因: th:text や th:each などの属性の記述ミス

解決策

Thymeleafの公式ドキュメントを参照しながら正しい構文を確認する。
Javaオブジェクトのプロパティ名とThymeleafで参照する変数名が一致しているか確認する。
エラーの特定が困難な場合:「th:」で始まる属性を一時的にコメントアウトし、Whitelabel Error Pageの表示が変化するかを確認する。

例: NGコード

<p th:text="${user.getName()}"></p>  <!-- getName()は不要 -->

修正後: OKコード

<p th:text="${user.name}"></p>

エラーの特定方法:

<!-- <p th:text="${user.name}"></p> -->

このように th: を含むコードをコメントアウトし、Whitelabel Error Pageが表示されなくなれば、その部分がエラーの原因である可能性が高いです。

3.3 Controllerの設定ミス

原因: @RequestMapping などの設定が間違っている。

解決策:

@Controller または @RestController の指定を確認する。
@GetMapping や @RequestMapping のパスが正しいかチェックする。

@Controller
public class UserController {
    @GetMapping("/user")
    public String getUserPage(Model model) {
        model.addAttribute("user", new User("John Doe"));
        return "user";  // user.htmlが templates/ に必要
    }
}

3.4 例外が適切に処理されていない

原因: Controller内で処理されない例外が発生している。

解決策

@ExceptionHandler を使って例外処理を行う。
ErrorController を作成し、カスタムエラーページを表示するようにする。

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public String handleException(Exception e, Model model) {
        model.addAttribute("message", e.getMessage());
        return "error";  // error.htmlを作成する
    }
}

4. カスタムエラーページを設定する

デフォルトの「Whitelabel Error Page」を避けるために、カスタムエラーページを作成する方法を紹介します。

4.1 src/main/resources/templates/error.html を作成する

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>Error</title>
</head>
<body>
    <h1>エラーが発生しました</h1>
    <p th:text="${message}"></p>
</body>
</html>

4.2 ErrorController を作成する

@Controller
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public String handleError(Model model) {
        model.addAttribute("message", "ページが見つかりません。");
        return "error";
    }
}