Springの例外処理「MaxUploadSizeExceededException」の対処法を初心者向けに完全解説

ファイル入出力の例外：MaxUploadSizeExceededException 等の対処

先生と生徒の会話形式で理解しよう

生徒

「Spring Bootでファイルをアップロードしようとしたら、エラーが出て処理できませんでした。どうしたらいいですか？」

先生

「そのエラーはおそらく、MaxUploadSizeExceededExceptionという例外が発生している可能性がありますね。これはファイルのサイズ制限を超えたときに発生するSpringの例外です。」

生徒

「それって、どこで設定を変えたり、どうやってキャッチしてエラーメッセージを出したりするんですか？」

先生

「とても良いところに気が付きましたね！では、初心者でもわかるように、Spring Bootでのファイルアップロードのサイズ制限の設定と、MaxUploadSizeExceededExceptionの対処方法を丁寧に解説していきましょう。」

1. Spring Bootのファイルアップロードで起きる例外とは？

「1. Spring Bootのファイルアップロードで起きる例外とは？」の重要ポイントを、初心者の方にも分かりやすく簡潔に解説します。

1. Spring Bootのファイルアップロードで起きる例外とは？

Spring Bootでファイルをアップロードする処理を実装する際、大きなファイルを送信するとMaxUploadSizeExceededExceptionという例外が発生することがあります。この例外は、アップロードされたファイルが設定された最大サイズを超えた場合に発生する例外です。

このようなエラーは、画像や動画などの大きなファイルを扱う場合に特に注意が必要です。初心者がつまずきやすいポイントなので、しっかり理解しておきましょう。

2. `MaxUploadSizeExceededException`が発生する原因

2. MaxUploadSizeExceededExceptionが発生する原因

MaxUploadSizeExceededExceptionは、Spring Bootでファイルアップロードのサイズが制限を超えたときに自動的にスローされます。たとえば、デフォルトでは1MBまでしか許可されていないことが多く、それを超えるファイルをアップロードすると例外が発生します。

3. アップロードサイズ制限の設定方法（`application.properties`）

3. アップロードサイズ制限の設定方法（application.properties）

ファイルサイズの上限は、application.propertiesまたはapplication.ymlで設定できます。以下のように設定すると、ファイルサイズの上限を変更できます。


spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB

max-file-sizeは1つのファイルのサイズ上限、max-request-sizeは複数ファイルを含むリクエスト全体の上限です。大きめのファイルを扱いたい場合は、適切に調整しましょう。

4. `MaxUploadSizeExceededException`をキャッチして丁寧なエラーメッセージを表示する

「4. MaxUploadSizeExceededExceptionをキャッチして丁寧なエラーメッセージを表示する」の重要ポイントを、初心者の方にも分かりやすく簡潔に解説します。

4. MaxUploadSizeExceededExceptionをキャッチして丁寧なエラーメッセージを表示する

Springでは、例外をハンドリングする方法として、@ControllerAdviceを使うのが一般的です。以下のようにMaxUploadSizeExceededExceptionを捕捉して、ユーザーにわかりやすいメッセージを返すことができます。


import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@ControllerAdvice
public class FileUploadExceptionAdvice extends ResponseEntityExceptionHandler {

    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public String handleMaxSizeException(MaxUploadSizeExceededException exc, RedirectAttributes redirectAttributes) {
        redirectAttributes.addFlashAttribute("message", "アップロードされたファイルサイズが大きすぎます。10MB以下のファイルを選択してください。");
        return "redirect:/uploadPage";
    }
}

このコードを使うことで、ファイルサイズの制限を超えたときに、エラーページにリダイレクトしつつ、フラッシュメッセージとしてエラー内容を表示できます。

5. HTMLフォーム側のファイルアップロード対応

HTML側でも、ファイルをアップロードするためのフォームを用意する必要があります。以下のように記述することで、ユーザーがファイルを選択して送信できます。


<form method="post" action="/upload" enctype="multipart/form-data">
    <input type="file" name="file" />
    <button type="submit">アップロード</button>
</form>

enctype="multipart/form-data"を忘れると、ファイルが正しく送信されないので注意しましょう。

6. コントローラー側でのファイル受け取り処理

Spring Bootでは、アップロードされたファイルをMultipartFileとして受け取ります。以下がその一例です。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

@Controller
public class FileUploadController {

    private static final String UPLOAD_DIR = "uploads/";

    @PostMapping("/upload")
    public String handleFileUpload(@RequestParam("file") MultipartFile file, RedirectAttributes redirectAttributes) {

        try {
            byte[] bytes = file.getBytes();
            Path path = Paths.get(UPLOAD_DIR + file.getOriginalFilename());
            Files.write(path, bytes);

            redirectAttributes.addFlashAttribute("message",
                "ファイル '" + file.getOriginalFilename() + "' のアップロードに成功しました！");
        } catch (IOException e) {
            redirectAttributes.addFlashAttribute("message",
                "ファイルの保存中にエラーが発生しました。");
        }

        return "redirect:/uploadPage";
    }
}

このコードで、アップロードされたファイルを指定したディレクトリに保存し、結果に応じてフラッシュメッセージを表示します。

7. 実行結果の例

「7. 実行結果の例」の重要ポイントを、初心者の方にも分かりやすく簡潔に解説します。

7. 実行結果の例

正常にファイルがアップロードされた場合と、サイズ制限を超えた場合の出力例は以下のとおりです。

成功時の出力例：


ファイル 'example.jpg' のアップロードに成功しました！

サイズ制限超過時の出力例：


アップロードされたファイルサイズが大きすぎます。10MB以下のファイルを選択してください。

8. ファイルサイズ制限以外の例外にも備えよう

IOExceptionやIllegalStateExceptionなど、ファイルアップロードでは他にもさまざまな例外が発生する可能性があります。それぞれに対して適切な例外処理を記述することで、アプリケーションの信頼性を高めることができます。

9. Spring Bootで使えるその他の便利なプロパティ

以下のようなプロパティも設定可能です：


spring.servlet.multipart.enabled=true
spring.servlet.multipart.location=/tmp
spring.servlet.multipart.file-size-threshold=2MB

一時ファイルの保存先や、ファイルサイズのしきい値なども変更できるので、用途に応じてカスタマイズしましょう。

まとめ

「まとめ」の重要ポイントを、初心者の方にも分かりやすく簡潔に解説します。

まとめ

MaxUploadSizeExceededExceptionはファイルアップロード開発で必ず覚えておきたい例外

Spring Bootでファイルアップロード機能を実装する際に発生しやすい例外の一つがMaxUploadSizeExceededExceptionです。画像アップロード機能やプロフィール画像登録機能、商品画像登録機能、帳票ファイル登録機能、動画アップロード機能などを実装すると、多くの場合でファイルサイズ制限を設定することになります。その際、設定したサイズを超えるファイルが送信されると、この例外が発生します。

初心者の方はエラー画面が表示されると不具合が発生したと思いがちですが、実際にはアプリケーションを安全に動作させるための正常な例外処理です。もしサイズ制限がなければ、非常に大きなファイルが送信され、サーバーのメモリ不足やストレージ不足を引き起こす可能性があります。そのため、Spring Bootではファイルサイズの上限を設定し、上限を超えた場合はMaxUploadSizeExceededExceptionを発生させる仕組みが用意されています。

実務では画像管理システム、ショッピングサイト、会員管理システム、社内申請システム、文書管理システムなど、多くのWebアプリケーションでファイルアップロード機能が利用されています。そのため、Spring Bootのファイルアップロード処理と例外処理は非常に重要な知識です。

application.propertiesの設定は必須

ファイルアップロード機能を作成するときは、まずapplication.propertiesでサイズ制限を設定することが重要です。設定を行わない場合、想定していないサイズ制限により利用者がファイルを登録できないことがあります。


spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB

max-file-sizeは一つのファイルの上限を表します。一方でmax-request-sizeはリクエスト全体の上限を表します。例えば五メガバイトの画像を三枚送信した場合、一ファイルごとの制限は満たしていてもリクエスト全体の制限に引っかかることがあります。そのため、それぞれの意味を理解して設定することが大切です。

実務では利用者がどのようなファイルを登録するかを考慮しながら設定値を決定します。プロフィール画像であれば数メガバイト程度、商品画像であれば数メガバイトから十数メガバイト程度、動画ファイルであればさらに大きな値を設定する場合があります。

例外処理を書くことでユーザーに優しいシステムになる

MaxUploadSizeExceededExceptionが発生したときに何も対処しなければ、利用者は難しいエラーメッセージを見ることになります。しかしControllerAdviceを利用して例外処理を行えば、利用者に分かりやすいメッセージを表示できます。


@ControllerAdvice
public class FileUploadExceptionAdvice {

    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public String handleMaxSizeException(
            MaxUploadSizeExceededException e,
            RedirectAttributes redirectAttributes) {

        redirectAttributes.addFlashAttribute(
                "message",
                "ファイルサイズが大きすぎます。");

        return "redirect:/uploadPage";
    }
}

このような例外処理を実装しておくことで、利用者は何が原因でアップロードに失敗したのかをすぐに理解できます。システム開発では機能を実装するだけではなく、エラーが発生した場合にどう案内するかも重要な設計要素です。

MultipartFileの理解も重要

Spring BootではアップロードされたファイルをMultipartFileとして受け取ります。MultipartFileにはファイル名取得、サイズ取得、ファイル保存など、多くの便利な機能が用意されています。


@PostMapping("/upload")
public String upload(
        @RequestParam("file") MultipartFile file) {

    System.out.println(file.getOriginalFilename());
    System.out.println(file.getSize());

    return "upload";
}

getOriginalFilenameは元のファイル名を取得します。getSizeはファイルサイズを取得します。これらを利用することで、アップロード前に独自のバリデーションを行うこともできます。

例えば画像ファイルのみ許可したり、特定の拡張子のみ許可したり、さらに厳密なチェックを追加したりできます。実務ではセキュリティ対策として拡張子確認やファイル形式確認を実施することも少なくありません。

ファイルアップロード機能で意識したいポイント

Spring Bootのファイルアップロード機能を開発するときは、サイズ制限だけではなく保存場所やファイル名管理にも注意が必要です。同じファイル名で保存すると上書きされる可能性があります。そのため実務では日時情報やデータベースの主キーを利用してファイル名を変更することが多くあります。


String fileName = itemId + ".png";

このように管理すると重複を防ぎやすくなります。また、アップロードされたファイルは利用者が自由に作成できるため、安全性も考慮する必要があります。不要な実行ファイルを保存できないようにしたり、保存先ディレクトリを制限したりすることも重要です。

Spring Bootのファイルアップロード機能を学習するときは、MultipartFileの使い方、application.propertiesの設定方法、ControllerAdviceによる例外処理、IOExceptionの対処方法、保存先ディレクトリ管理、セキュリティ対策までまとめて理解しておくと実務でも役立ちます。

今回学習したMaxUploadSizeExceededExceptionは単なるエラーではありません。利用者の操作ミスや予期しないデータ送信からシステムを守るための大切な仕組みです。Spring Bootの例外処理を正しく理解し、利用者に分かりやすいメッセージを表示できるようになると、より品質の高いWebアプリケーションを開発できるようになります。ファイルアップロード機能は多くのシステムで利用されるため、この機会にしっかり理解しておきましょう。

先生と生徒の振り返り会話

生徒

Spring Bootでファイルアップロードをするときは、ただMultipartFileを受け取るだけではなくて、サイズ制限も考えないといけないことが分かりました。

先生

その通りです。実務では画像アップロードやファイル登録機能がよく使われますので、MaxUploadSizeExceededExceptionは非常によく見る例外です。

生徒

application.propertiesでmax-file-sizeとmax-request-sizeを設定する意味も理解できました。一つのファイルとリクエスト全体で役割が違うのですね。

先生

よく理解できています。サイズ制限を適切に設定することでサーバーへの負荷を抑えることができます。

生徒

ControllerAdviceを使うと例外処理をまとめて管理できることも学びました。エラーが発生したときに利用者へ分かりやすいメッセージを表示できるのは便利ですね。

先生

そうですね。実務ではエラーを発生させないことも大切ですが、エラーが発生したときにどう案内するかも同じくらい重要です。

生徒

MultipartFileのgetOriginalFilenameやgetSizeも便利そうです。ファイル名やサイズを確認して独自チェックもできそうですね。

先生

その考え方は実務でも役立ちます。画像形式の確認や拡張子確認なども組み合わせることで、より安全なファイルアップロード機能を作ることができます。

生徒

Spring Bootのファイルアップロード処理は思ったより奥が深いですね。でも今回で流れがかなり理解できました。

先生

とても良い理解です。MaxUploadSizeExceededException、MultipartFile、ControllerAdvice、application.propertiesの設定はセットで覚えておくと、今後のSpring Boot開発で必ず役立ちます。ファイルアップロード機能を作る機会があれば、ぜひ今回の内容を思い出してください。

スタースクール：社会人向け実務教育プロジェクト

【職業訓練講師が直接指導】

社会人向けSpring Boot実務セミナー｜職業訓練講師が教えるWebシステム構築の極意

Java入門からSpring Boot実務まで。現場で絶賛される「設計の型」を最短距離で習得。

技術記事の内容を、自分の「スキル」へ変える。

職業訓練講師が最短攻略！社会人向けSpring Bootによる「商用Webシステム構築」の実践。

モダンJava開発の事実上の標準Spring Boot。本セミナーでは、その圧倒的利便性の核にある「DI（依存性の注入）」を完全解剖。「設定より規約」を体現した効率的なアーキテクチャ設計を学び、ThymeleafやSpring Data JPAを組み合わせた、現場で必須となるWebシステムの作り方を60分で濃縮体験します。