Spring Boot Whitelabel Error Pageの原因と直し方

「Whitelabel Error Page」は、Spring Boot がエラーのときに出す既定の画面です。 エラーそのものの名前ではないので、まず画面の最後の行にある status= の数字を見ます。404 なら「URL に対応する処理が見つからない」、500 なら「処理の途中で例外が起きた」で、原因の探し方がまったく違います。

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

Fri Oct 10 18:00:00 JST 2026
There was an unexpected error (type=Not Found, status=404).

2行目の「no explicit mapping for /error」は、「エラー画面を自分で用意していないので、既定の画面を出しています」という意味です。/error の設定が原因ではありません。 この記事では、ステータスごとの原因を確認順に並べ、最後に独自のエラー画面に置き換える方法と、Spring Boot 4 で名前が変わった設定をまとめました。

確認環境：Spring Boot 4.1.1 の公式リファレンス、Spring Framework 7.0 のリファレンス、Spring Boot 4.0 の移行に関する公式・OpenRewrite の資料で確認（確認日 2026年10月10日）。

まず status で分ける

500 のときは、画面ではなくコンソール（ログ）を見ます。 画面には例外の詳細が出ない設定が既定ですが、ログにはスタックトレースが出ています。

404 の原因と直し方

原因1：コントローラーが @SpringBootApplication のパッケージの外にある

Spring Boot は、@SpringBootApplication を付けたクラスと同じパッケージとその下だけを探して、コントローラーを登録します。

src/main/java/
├─ com/example/demo/DemoApplication.java     ← @SpringBootApplication
├─ com/example/demo/web/HelloController.java ← 見つかる（demo の下）
└─ com/example/web/UserController.java       ← 見つからない（demo の外）

UserController の URL を開くと 404 になります。コントローラーを com.example.demo の下に移すのが基本の直し方です。どうしても外に置くなら、@SpringBootApplication(scanBasePackages = "com.example") で探す範囲を広げます。

原因2：URL と @RequestMapping が合っていない

起動ログを DEBUG にすると、登録された URL の一覧が出ます。

logging.level.org.springframework.web=DEBUG

原因3：URL の末尾にスラッシュを付けている（Spring Boot 3 以降）

Spring Framework 6（Spring Boot 3）から、末尾のスラッシュは別の URL として扱われるようになりました。@GetMapping("/hello") に /hello/ でアクセスすると 404 です。Spring Boot 2 から上げたときに急に出る原因の1つです。

URL をどちらかにそろえるか、両方を受けたいときは @GetMapping({"/hello", "/hello/"}) のように両方を書きます。

原因4：context-path を付け忘れている

application.properties に次の設定があると、すべての URL の前に /app が付きます。

server.servlet.context-path=/app

http://localhost:8080/hello ではなく http://localhost:8080/app/hello で開きます。起動ログの Tomcat started on port 8080 (http) with context path '/app' で確認できます。

原因5：静的ファイル（HTML・CSS・画像）の置き場所が違う

Spring Boot が静的ファイルを配信するのは、クラスパスの次の4つのフォルダです（src/main/resources の下に作ります）。

• templates/ の下の HTML は、URL で直接は開けません（コントローラーから返すテンプレート用です）
• src/main/webapp/ は war で動かすときだけ使われ、jar では無視されます
• URL に static は含めません（/static/css/app.css ではなく /css/app.css）

Spring Boot 3.2 以降は、合う処理も静的ファイルも無いとき、ログに No static resource ○○. と出ます（NoResourceFoundException）。

原因6：SPA（React・Vue・Angular）の画面で再読み込みすると 404

フロントエンドのルーター（履歴モード）が作った /about のような URL で再読み込みすると、その URL がサーバーに送られ、Spring Boot 側には対応する処理が無いので 404 になります。画面の URL をサーバーで index.html に転送します。

@Controller
public class SpaForwardController {

    // 拡張子の無いパス（/about、/users/1 など）を index.html に渡す。/api は除く
    @GetMapping({"/{path:^(?!api$)[^.]*}", "/{path:^(?!api$)[^.]*}/**"})
    public String forward() {
        return "forward:/index.html";
    }
}

存在しない URL も 200 で index.html を返すことになるため、検索エンジン向けの404の扱いはフロントエンド側で決めます。

500 の原因と直し方

原因1：処理中の例外

コンソールに出ている最初の Caused by: と、自分のパッケージ名が出てくる行を探します。NullPointerException、SQL の例外、外部 API の例外などが代表です。画面に詳細を出したいときは、開発環境だけ次の設定にします（Spring Boot 4 の名前。3.x は server.error.*）。

# 開発環境だけで使う（本番では出さない）
spring.web.error.include-message=always
spring.web.error.include-stacktrace=always
spring.web.error.include-binding-errors=always

原因2：テンプレートが見つからない（Thymeleaf）

org.thymeleaf.exceptions.TemplateInputException: Error resolving template [hello], template might not exist or might not be accessible by any of the configured Template Resolvers

@Controller のメソッドが return "hello"; を返すと、Thymeleaf は src/main/resources/templates/hello.html を探します。ファイル名、フォルダ（templates/）、先頭のスラッシュ（"/hello" だと jar で見つからないことがある）を確認します。

原因3：JSON を返したいのに @Controller を付けている

@Controller のメソッドが返す文字列は、ビュー（テンプレート）の名前として扱われます。JSON や文字列をそのまま返したいなら @RestController（または メソッドに @ResponseBody）にします。テンプレートエンジンが無い構成で @Controller からビュー名を返すと、Circular view path の例外（500）や、存在しない URL への転送（404）になります。

405・400・401／403

Spring Security を入れていると、本当のエラーが 403 に隠れる

コントローラーで例外が起きると、Spring Boot は内部で /error に転送してエラー画面を作ります。Spring Security で /error が許可されていないと、この転送が止められ、本当は 500 なのに 401／403 が返ることがあります。/error を許可しておきます。

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
            .requestMatchers("/error", "/css/**", "/js/**").permitAll()
            .anyRequest().authenticated())
        .formLogin(Customizer.withDefaults());
    return http.build();
}

独自のエラー画面に置き換える

いちばん簡単：error フォルダに HTML を置く

ステータス番号のファイル名で置くと、Whitelabel の代わりに表示されます。

src/main/resources/
├─ static/error/404.html          ← 静的な HTML（そのまま表示）
└─ templates/error/
   ├─ 404.html                    ← Thymeleaf のテンプレート（中で ${status} などを使える）
   └─ 5xx.html                    ← 500〜599 をまとめて

Thymeleaf のテンプレートでは、次の値を使えます（message などは設定で出すようにしたときだけ値が入ります）。

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" lang="ja">
<head><meta charset="UTF-8"><title>ページが見つかりません</title></head>
<body>
  <h1>ページが見つかりません（<span th:text="${status}">404</span>）</h1>
  <p>URL：<span th:text="${path}">/xxx</span></p>
  <p th:text="${timestamp}"></p>
  <a href="/">トップへ戻る</a>
</body>
</html>

Whitelabel 画面を出さない設定

# Spring Boot 4.x
spring.web.error.whitelabel.enabled=false

# Spring Boot 3.x まで
server.error.whitelabel.enabled=false

この設定だけで独自の画面を用意しないと、サーバー（Tomcat など）の既定のエラー画面が出ます。上の error フォルダの HTML と組み合わせて使います。

API は JSON で返す：@RestControllerAdvice と ProblemDetail

REST API では、ブラウザ向けの画面ではなく JSON を返します。Spring Boot は API の呼び出し（Accept: application/json）には、もともと JSON でエラーを返します。形をそろえたいときは、RFC 9457 の Problem Details 形式を使えます。

spring.mvc.problemdetails.enabled=true

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ProblemDetail handleNotFound(UserNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("ユーザーが見つかりません");
        return pd;
    }
}

{
  "type": "about:blank",
  "title": "ユーザーが見つかりません",
  "status": 404,
  "detail": "id=99 のユーザーはありません",
  "instance": "/api/users/99"
}

Spring Boot 4 で名前が変わった設定

Spring Boot 4 では、エラー処理の設定が server.error.* から spring.web.error.* に変わりました。3.x までの名前のままだと、設定が効かずに Whitelabel 画面が出続けます。

include-message・include-stacktrace・include-binding-errors は既定で never（出さない）、include-exception は false です。本番でスタックトレースを画面に出すと、内部の構成が外から読めてしまうため、開発環境のプロファイル（application-dev.properties など）だけで有効にします。移行時は spring-boot-properties-migrator を一時的に依存に入れると、名前が変わった設定を起動ログで教えてくれます。

確認の手順（チェックリスト）

よくある質問

Q. 起動直後に http://localhost:8080/ を開くと Whitelabel の404になります。 A. / に対応するコントローラーも、static/index.html も無いためです。異常ではありません。static/index.html を置くか、@GetMapping("/") を作ります。

Q. 「This application has no explicit mapping for /error」を直す必要はありますか。 A. この行はそのままで問題ありません。独自のエラー画面が無いことを示しているだけです。原因は下の行の status= のほうにあります。独自の画面にしたいときは templates/error/404.html などを置きます。

Q. 同じ URL が IDE では動くのに、jar にすると404になります。 A. src/main/webapp/ に置いたファイル（jar では含まれない）、テンプレート名の先頭のスラッシュ、大文字小文字の違い（Windows の開発環境では区別されず、Linux のサーバーでは区別される）が多い原因です。

Q. Whitelabel 画面を消すと、エラーの原因が分からなくなりませんか。 A. 画面の表示とログは別です。画面を独自のものにしても、例外はログに出ます。原因はログで確認し、画面には利用者向けの案内だけを出すのが一般的な形です。

まとめ

• Whitelabel Error Page はエラーの名前ではなく既定の画面。最後の行の status= で原因を分ける
• 404：コントローラーが @SpringBootApplication のパッケージの外、URL の違い、末尾スラッシュ（Spring Boot 3 以降は別 URL）、context-path、静的ファイルの場所
• 500：コンソールのスタックトレースを見る。テンプレートが見つからない、@Controller と @RestController の取り違えも多い
• Spring Security を使うなら /error を許可しないと、本当のエラーが 401／403 に隠れる
• 独自の画面は templates/error/404.html・5xx.html を置くだけ。API は @RestControllerAdvice と ProblemDetail
• Spring Boot 4 では設定が spring.web.error.* に変わった。3.x までの server.error.* のままだと効かない

参考・出典

確認日はいずれも 2026年10月10日です。

• Spring Boot リファレンス「Servlet Web Applications（Error Handling・Static Content）」：https://docs.spring.io/spring-boot/reference/web/servlet.html
• Spring Boot リファレンス「Using the @SpringBootApplication Annotation」：https://docs.spring.io/spring-boot/reference/using/using-the-springbootapplication-annotation.html
• Spring Boot「System Requirements」（4.1.1）：https://docs.spring.io/spring-boot/system-requirements.html
• Spring Boot「Spring Boot 4.0 Migration Guide」：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
• OpenRewrite「Migrate Spring Boot properties to 4.0」（server.error.* → spring.web.error.* の対応）：https://docs.openrewrite.org/recipes/java/spring/boot4/springbootproperties_4_0
• Spring Framework「Spring Framework 6.0 Release Notes（末尾スラッシュの扱い）」：https://github.com/spring-projects/spring-framework/wiki/Upgrading-to-Spring-Framework-6.x
• Spring Framework リファレンス「Error Responses（ProblemDetail）」：https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
• RFC 9457「Problem Details for HTTP APIs」：https://www.rfc-editor.org/rfc/rfc9457

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。