独自のエラー画面（error.html）を作ってみよう【Spring初心者向け完全ガイド】

Springで独自のエラー画面（error.html）を作ってみよう

新人と先輩の会話形式で理解しよう

新人

「先輩、Springアプリでエラーが起きたときに、英語の画面が出てきたんですけど、あれって直せるんですか？」

先輩

「あれはSpring Bootの標準のエラーページなんだけど、自分でエラー画面をカスタマイズすることもできるよ。」

新人

「へえ、じゃあ自分でデザインしたエラー画面を表示できるんですか？」

先輩

「もちろん。今回はerror.htmlを使って、Springのエラー画面をカスタマイズする方法を一緒に学んでいこう！」

1. Springのエラー画面の仕組みとは？

Spring Bootでは、アプリケーション内でエラーが発生した場合、自動的に「Whitelabel Error Page（ホワイトラベルエラーページ）」という簡易的なエラー画面が表示されます。これは、Spring Bootが用意しているデフォルトのエラー表示機能です。

たとえば、存在しないURLにアクセスした場合や、コントローラーの処理中に例外が発生した場合に、このページが表示されます。英語表記で簡素なデザインのため、ユーザーにはあまり親切とは言えません。

こうした背景から、企業の業務システムや商用サービスでは、「Spring エラー画面カスタマイズ」が求められるケースが非常に多くなります。見た目を整えたり、ユーザーに案内メッセージを追加したりすることで、利便性を高めることができるからです。

Spring Bootでは、特別な設定をしなくても、ある場所にerror.htmlという名前のテンプレートを用意するだけで、自動的に独自のエラー画面に切り替わる仕組みが用意されています。

そのテンプレートの配置先は次のとおりです。


src/main/resources/templates/error.html

この場所にHTMLファイルを作成することで、「Spring error.html 作成方法」としての基本的な準備が整います。

2. なぜ独自のエラー画面が必要なのか？

初心者の方にとっては、「標準の画面でも動くならそれでいいのでは？」と思うかもしれません。しかし、エラーページのカスタマイズは、ユーザー体験やセキュリティの面からも非常に重要な意味を持ちます。

まず、標準の「Whitelabel Error Page」には、内部のスタックトレースやパス情報など、開発中の詳細な情報が表示されることがあります。これをそのまま公開してしまうと、セキュリティリスクとなる可能性があります。

また、ユーザーが操作ミスをした場合や、サーバー側で一時的な障害が発生した場合にも、冷たい英語の画面では不安を与えてしまいます。

そこで、独自のerror.htmlを作ることで、たとえば次のような利点が得られます。

ユーザーにやさしい日本語のメッセージを表示できる
トップページへのリンクや、カスタマーサポートへの案内を追加できる
デザインを整えて、ブランドイメージに合った画面にできる
予期しないエラーが起きた場合でも、冷静に誘導できる

とくに業務システムでは、「Spring エラー画面カスタマイズ」を適切に行うことで、クライアントからの信頼度が大きく変わってきます。

また、独自のエラー画面は、開発チームの中で「エラー処理の統一ルール」を持つ上でも有効です。テンプレートを共通化しておけば、新しいエラー発生時にも安心して対応できます。

Spring Bootでは、特別な設定ファイルを記述しなくても、src/main/resources/templates配下にerror.htmlを作成するだけで、独自のテンプレートが優先的に適用されます。

この仕組みを活用して、ユーザーにやさしいシステム設計を心がけていきましょう。

3. error.htmlの基本構成を作ってみよう

では実際に、Spring Bootで使用できるerror.htmlを作成してみましょう。テンプレートエンジンとしてはThymeleafを使用します。

ファイルの配置場所は以下のとおりです。これは「Spring error.html 配置場所」として非常に重要なポイントです。


src/main/resources/templates/error.html

このファイルは、Spring Bootのエラーハンドリング機構により、自動的に呼び出される仕組みになっています。テンプレートの中では、エラー内容に応じて動的にメッセージを表示したり、リンクを表示することも可能です。

以下に、基本的なerror.htmlのサンプルコードを示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>エラーが発生しました</title>
</head>
<body>
    <h1>エラーが発生しました</h1>
    <p th:text="'ステータスコード: ' + ${status}"></p>
    <p th:text="'エラーメッセージ: ' + ${error}"></p>
    <p th:text="'詳細: ' + ${message}"></p>
    <p><a th:href="@{/}">トップページに戻る</a></p>
</body>
</html>

このテンプレートでは、${status}や${error}といった変数を使って、Springが提供するエラー情報を画面に表示しています。

たとえば、404エラーが発生した場合には「ステータスコード: 404」「エラーメッセージ: Not Found」などが出力されます。

このように、error.htmlに最小限の情報を記載しておくだけでも、「Spring エラー画面カスタマイズ」の第一歩としては十分に有効です。

4. HTTPステータスごとにエラーページを切り替えるには？

さて、前のセクションでは1つのerror.htmlですべてのエラーに対応する方法を紹介しましたが、実際の運用ではHTTPステータスコードごとに異なるエラー画面を用意したくなることがあります。

たとえば、「ページが見つかりません（404）」と「サーバーエラー（500）」では、ユーザーへの案内文や画面構成も異なるのが理想です。

Spring Bootでは、このようにHTTPステータスごとにテンプレートを分けることが可能です。以下に設定方法を紹介します。

まず、src/main/resources/templates/errorというフォルダを作成し、その中にHTTPステータスコードを名前としたHTMLファイルを配置します。


src/main/resources/templates/error/404.html
src/main/resources/templates/error/500.html

このルールに従ってファイルを作ると、「Spring エラー画面 404」などの特定コードに対応するカスタム画面をSpringが自動的に読み込んでくれるようになります。

それでは、それぞれのファイルの中身を見ていきましょう。

404エラー画面（404.html）の例）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ページが見つかりません</title>
</head>
<body>
    <h1>お探しのページは見つかりませんでした</h1>
    <p>指定されたURLが存在しないか、移動した可能性があります。</p>
    <p><a th:href="@{/}">トップページに戻る</a></p>
</body>
</html>

500エラー画面（500.html）の例）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>サーバーエラー</title>
</head>
<body>
    <h1>内部エラーが発生しました</h1>
    <p>現在、サーバー内部で問題が発生しています。時間をおいて再度お試しください。</p>
    <p><a th:href="@{/}">トップページに戻る</a></p>
</body>
</html>

このように、templates/errorディレクトリの中にステータスコードに対応するファイルを設置するだけで、Spring Bootが自動的に対応してくれます。これが「Spring エラー画面カスタマイズ」における柔軟な設計の一例です。

ここまで紹介した方法は、Gradle＋Pleiades環境でSpring Bootを実行している初心者にとっても、非常に取り組みやすい方法です。@Controllerを使ったMVC構成の中でも、これらのテンプレートは問題なく連携します。

プロジェクトの品質を高めるためにも、最低限「error.html」と「404.html」「500.html」を準備しておくことをおすすめします。

また、開発段階では実際にエラーを発生させて画面が切り替わるかを確認しておきましょう。例えば、存在しないURLにアクセスすれば簡単に404エラーをテストできます。

このような仕組みを知っておくことで、将来的により高度な「Spring エラー画面カスタマイズ」へと発展させていく基盤となります。

5. よくある間違いと表示されない時の対処法

ここまで順調に設定を進めてきたつもりでも、「Spring error.html 表示されない」といった事態に直面することがあります。初心者の方にとっては、どこでつまずいているのか分からず、非常に不安になる瞬間です。

そこでこのセクションでは、error.htmlが表示されない主な原因とその対処法について、具体的に紹介していきます。

ファイル名のミス：error.htmlではなくerrors.htmlなどと誤って命名しているケース。
配置場所のミス：src/main/resources/templatesではなく、誤ってstaticフォルダなどに置いてしまうケース。
HTMLテンプレートの拡張子ミス：拡張子が.htmや.txtになっていると、Springはテンプレートとして認識しません。
HTTPステータスコードの指定漏れ：templates/error/404.htmlのような特定コード用のテンプレートが必要な場面で、用意されていないとWhitelabel Error Pageが出てしまうこともあります。
Thymeleafの依存関係が不足：Spring Bootでテンプレートを扱うには、thymeleafの依存ライブラリがGradleに追加されている必要があります。

とくにGradleでの開発環境では、依存ライブラリの追加漏れが原因でテンプレートが無効になるケースもあるため、pleiadesの「プロジェクトの構成」メニューでSpring WebとThymeleafが有効になっているかを確認しましょう。

6. 実践で使えるエラー画面の工夫（ユーザー配慮・案内リンクなど）

基本的なerror.htmlや404.htmlの作成ができたら、次は実際の運用を見据えて、ユーザーにとって親切な画面を目指しましょう。ここでは、実務でよく使われる工夫をいくつか紹介します。

まず、画面の中に「トップページへのリンク」や「問い合わせページへの誘導リンク」を設置することで、ユーザーが迷子にならずに済む設計になります。次のような文言を入れると、より丁寧な印象になります。


<p>ご不便をおかけして申し訳ありません。</p>
<p><a th:href="@{/}">トップページに戻る</a>か、<a th:href="@{/contact}">お問い合わせ</a>ページをご利用ください。</p>

また、ビジネス向けのWebアプリケーションであれば、「営業時間内におかけ直しください」などの案内文や、「〇時からメンテナンス中」といった情報を動的に出す工夫も考えられます。

「Spring カスタムエラーページ」としての信頼感を高めるためにも、たとえば以下のような表現もおすすめです。

「しばらくしてから再度アクセスしてください」
「この問題が続く場合は管理者までご連絡ください」
「URLが正しいかどうかをご確認ください」

こうした細やかな文言ひとつひとつが、ユーザー体験の質を左右します。特に日本語圏のユーザーにとっては、お詫びの一言があるだけでも安心感が大きく変わります。

7. 開発中と本番環境でエラー表示を切り替える方法（application.properties）

最後に、開発時と本番環境で表示するエラー情報を切り替える方法について紹介します。Spring Bootでは、設定ファイルapplication.propertiesを使って、こうした切り替えが簡単に行えます。

開発中はスタックトレースなど詳細な情報を表示してもよいですが、本番環境では情報漏洩を避けるために詳細を出さないほうが安全です。

次のような設定を使って、Spring Bootのデフォルトエラーメッセージの表示をコントロールできます。


# エラーページの詳細メッセージを非表示にする（本番環境向け）
server.error.include-message=never
server.error.include-binding-errors=never
server.error.include-stacktrace=never

上記の設定を使えば、本番環境で発生したエラー時に、${message}や${trace}などがテンプレートに渡されなくなります。

逆に、開発中に詳しい情報を確認したい場合は、以下のように設定することで、テンプレートでスタックトレースを見ることができます。


# 開発時の詳細表示
server.error.include-message=always
server.error.include-stacktrace=always

このようにapplication.propertiesを使えば、実行環境ごとに柔軟にエラーの表示方法を切り替えることができます。環境ごとの設定をapplication-dev.propertiesやapplication-prod.propertiesなどに分けておくことで、切り替え運用もスムーズになります。

以上のような工夫と対策を取り入れることで、「Spring エラー画面本番環境」でも安心して運用できる仕組みが整います。

初心者の方も、この基本をしっかり理解しておけば、実務でのトラブル対応やユーザー配慮のある設計にも自信を持って取り組めるようになります。