HttpMessageNotReadableExceptionの直し方｜原因一覧

HttpMessageNotReadableException は、@RequestBody で受け取るリクエストの本文（JSON）を Java のオブジェクトに変換できなかったときの例外です。 Spring は 400 Bad Request を返し、ログに次のような WARN を1行出します。

WARN ... o.s.w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error: Cannot deserialize value of type `int` from String "abc": not a valid `int` value]

直し方は、JSON parse error: の後ろの文（Jackson の例外の文）を読んで、送る側の JSON か、受け取る側のクラスのどちらかを合わせることです。 文の書き出しで原因がほぼ決まります。

Spring Boot 4 の Jackson は 3 系（パッケージが tools.jackson）です。 Boot 3 までの Jackson 2 と既定値が違い、Boot 3 では通っていた JSON が Boot 4 で 400 になることがあります（下の「Boot 4 で変わった点」）。

確認環境：Spring Boot 4.1.1（Spring Framework 7.0.9、Jackson 3.1.5 は Boot の依存管理の版）、OpenJDK 25.0.4.1（Linux）。Jackson 3.1.5（jackson-core・jackson-databind）は GitHub のタグのソースからビルドし、この記事の表の JSON を実際に読ませて例外のクラスとメッセージを取りました。Spring 側のメッセージ（JSON parse error:・Required request body is missing:・ログの Resolved [ の形）と 400 になる流れは、Spring Framework v7.0.9 のソース（AbstractJacksonHttpMessageConverter・RequestResponseBodyMethodProcessor・DefaultHandlerExceptionResolver）で確かめました。Boot の既定値は v4.1.1 のソースとドキュメントで確かめています（確認日 2026年10月13日）。

メッセージの読み方：Spring の部分と Jackson の部分

ログの1行は、3つの部分でできています。

Resolved [org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error: Cannot deserialize value of type `int` from String "abc": not a valid `int` value]
         └───────────── Spring の例外 ──────────────────────┘ └ Spring ┘ └──────────── Jackson の例外の文 ────────────┘

Spring Framework 7.0.9 の AbstractJacksonHttpMessageConverter は、Jackson の例外を受けて次のように包み直しています。

catch (InvalidDefinitionException ex) {
    throw new HttpMessageConversionException("Type definition error: " + ex.getType(), ex);
}
catch (JacksonException ex) {
    throw new HttpMessageNotReadableException("JSON parse error: " + ex.getOriginalMessage(), ex, inputMessage);
}

ここから分かることは3つです。

項目の場所を知りたいときは、原因の例外（ex.getCause()）を見ます。 Jackson 3.1.5 で取った、同じ失敗の全文です。

Cannot deserialize value of type `int` from String "abc": not a valid `int` value
 at [Source: REDACTED (`StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION` disabled); byte offset: #7] (through reference chain: com.example.demo.UserForm["age"])

byte offset: #7 は本文の先頭から何バイト目か、reference chain はどの項目かです。Source: REDACTED は、本文の中身をメッセージに入れない Jackson の既定の動きです（個人情報がログに出るのを防ぐため）。

原因1：本文が空（Required request body is missing）

Resolved [org.springframework.http.converter.HttpMessageNotReadableException: Required request body is missing: public com.example.demo.UserResponse com.example.demo.UserController.create(com.example.demo.UserForm)]

この文は Jackson ではなく Spring が出します。 RequestResponseBodyMethodProcessor は、変換の結果が null で、@RequestBody が必須（required = true、既定）のときに、メソッドのシグネチャを付けて投げます。

本文が任意なら、@RequestBody(required = false) にして、引数が null のときの処理を書きます。

原因2：JSON の書き方の誤り（StreamReadException）

Jackson 2 の JsonParseException は、Jackson 3 では tools.jackson.core.exc.StreamReadException になりました（Jackson 3.1.5 のソースに JsonParseException はありません）。実際に読ませた結果です。

Unrecognized token 'name' は、本文が JSON でない典型です。 jQuery の $.ajax で data にオブジェクトを渡すと、既定ではフォーム形式（name=a&age=1）で送られます。JSON.stringify(data) で文字列にして送ります。

await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "山田", age: 30 }),
});

Unexpected end-of-input は、JSON を手で組み立てて括弧が足りないとき、またはプロキシなどで本文が途中で切れたときに出ます。

Content-Type を付け忘れたときは、この例外ではありません。 application/json 以外（text/plain など）だと HttpMediaTypeNotSupportedException で 415 になります。

原因3：型が合わない（InvalidFormatException・MismatchedInputException）

受け取るクラスの例です。

public record UserForm(String name, Integer age, LocalDate birthday, Status status, Boolean admin, List<String> tags) {}
public enum Status { ACTIVE, INACTIVE }

InvalidFormatException は「値の形が違う」、MismatchedInputException は「JSON の種類（文字列・配列・オブジェクト）が違う」と覚えると区別しやすくなります。 InvalidFormatException は MismatchedInputException の子クラスです。

逆に、次の値はエラーにならずに変換されました。 気づかないまま値が変わることがあります。

小数を整数に入れたくないときは spring.jackson.deserialization.accept-float-as-int=false で、1.5 をエラーにできます（Jackson 3.1.5 の既定は true）。

原因4：プリミティブ型と null（Boot 4 で増えたエラー）

JSON parse error: Cannot map `null` into type `int` (set `DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES` to 'false' to allow)

Jackson 3 では FAIL_ON_NULL_FOR_PRIMITIVES の既定が true になりました。 int・boolean などのプリミティブ型に null が来るとエラーです。Jackson 3.1.5 で試した結果は次のとおりです。

record（やコンストラクタで受け取るクラス）では、項目を省略しただけでもエラーになります。 コンストラクタの引数に渡す値が無いと、Jackson は null を渡そうとするためです。Boot 3 では通っていた画面が、Boot 4 にしたら 400 になる、という形でよく出ます。

直し方は3つあります。

Boot 4 には、Jackson 2 に近い既定値へまとめて戻す spring.jackson.use-jackson2-defaults=true もあります。Jackson 3.1.5 の configureForJackson2() で、上の record に {"name":"a"} を読ませると、age が 0 で成功しました。入力チェックの書き方は関連記事「Spring Bootバリデーション一覧｜@Validと@Validated」で扱っています。

原因5：日付・時刻の形式（InvalidFormatException）

LocalDate・LocalDateTime は、既定では ISO 8601 の形（2026-10-13・2026-10-13T09:00:00）で受け取ります。Jackson 3 では日付・時刻の型の対応が jackson-databind に入っており、Jackson 2 のように jackson-datatype-jsr310 を足す必要はなくなりました。

"2026/10/13" のときの全文は次のとおりです。

JSON parse error: Cannot deserialize value of type `java.time.LocalDate` from String "2026/10/13": Failed to deserialize `java.time.LocalDate` (with format 'Value(Year,4,10,EXCEEDS_PAD)'-'Value(MonthOfYear,2)'-'Value(DayOfMonth,2)'): (java.time.format.DateTimeParseException) Text '2026/10/13' could not be parsed at index 4

index 4 は「先頭から5文字目で読めなくなった」という意味です。 2026/ の / で止まっています。

送る側を ISO 形式にできないときは、項目に @JsonFormat を付けます。

import com.fasterxml.jackson.annotation.JsonFormat;

public record SearchForm(
        @JsonFormat(pattern = "yyyy/MM/dd") LocalDate from,
        @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime createdAt) {}

@JsonFormat は Jackson 3 でも com.fasterxml.jackson.annotation のままです。 Jackson 3 は注釈のライブラリ（jackson-annotations）を 2 系のまま使うためです。@JsonFormat(pattern = "yyyy/MM/dd") を付けると、今度は "2026-10-13" がエラーになりました（両方を受けたいときは独自のデシリアライザが要ります）。

spring.jackson.date-format は java.util.Date 用の設定で、LocalDate には効きません。 LocalDate の形式は @JsonFormat で決めます。日付の扱い全般は関連記事「Jackson ObjectMapperの使い方｜JSON変換・日付・record」で扱っています。

原因6：enum に無い値

JSON parse error: Cannot deserialize value of type `com.example.demo.Status` from String "active": not one of the values accepted for Enum class: [INACTIVE, ACTIVE]

[INACTIVE, ACTIVE] の並びは、enum の定義順とは限りません。 受け付ける値の一覧として読みます。

1つの enum だけ変換のしかたを変えたいときは、enum に @JsonCreator を付けた static メソッドを書き、文字列から定数を返します。

原因7：配列とオブジェクトの取り違え・JSON が2つ

from Array value は「配列が来たがオブジェクトを期待していた」、from Object value はその逆です。 1件を送るか一覧を送るかを、画面と API で揃えます。

後ろに余計な JSON があるときのエラーも、Jackson 3 から既定で出ます（FAIL_ON_TRAILING_TOKENS の既定が true）。

原因8：文字コード（Invalid UTF-8 start byte）

JSON parse error: Invalid UTF-8 start byte 0x8e

{"name":"山田"} を Shift_JIS のバイト列で送ると、このエラーになりました。JSON の文字コードは UTF-8 が標準です（RFC 8259）。

Spring Framework 7.0.9 のソースでは、Content-Type の charset が UTF-8・UTF-16・UTF-32 以外のとき、その charset の Reader で読みます。既存のシステムから Shift_JIS で送られてくる場合、送る側が Content-Type: application/json;charset=Shift_JIS を付ければ読めます。付けられないときは送る側を UTF-8 にします。

原因9：クラスを作れない

引数ありコンストラクタのクラスは、引数の名前がクラスファイルに残っていれば読めます。 Spring Boot の Gradle プラグインと Maven の親 POM は、既定で -parameters を付けてコンパイルします。IDE の設定で外れている、自前の pom で親を使っていない、という場合にこのエラーになります。

Kotlin の data class も同じ文で失敗します。 jackson-module-kotlin（Jackson 3 の座標は tools.jackson.module:jackson-module-kotlin）を依存に足すと、Boot が自動で登録します（spring.jackson.find-and-add-modules の既定が true）。start.spring.io で Kotlin を選ぶと最初から入っています。

record の compact コンストラクタで投げた例外も、この例外になります。

public record Range(LocalDate from, LocalDate to) {
    public Range {
        if (from != null && to != null && from.isAfter(to)) {
            throw new IllegalArgumentException("from は to と同じか前の日付にします");
        }
    }
}

JSON parse error: Cannot construct instance of `com.example.demo.Range`, problem: from は to と同じか前の日付にします

例外は ValueInstantiationException（JacksonException の仲間）なので 400 です。Cannot construct instance の原因の全体は、関連記事「Jackson Cannot construct instanceの直し方」で扱っています。

原因10：知らない項目（Boot 4 の既定では起きない）

JSON parse error: Unrecognized property "email" (class com.example.demo.Plain), not marked as ignorable

Jackson 3 では FAIL_ON_UNKNOWN_PROPERTIES の既定が false です。 クラスに無い項目が来ても無視されます。上の文は、わざと true にしたときの結果です（Jackson の全文には (2 known properties: "age", "name") が続きますが、Spring のログには出ません）。項目名の誤りに気づきたいときは spring.jackson.deserialization.fail-on-unknown-properties=true にします。詳しくは関連記事「Jackson UnrecognizedPropertyExceptionの直し方」で扱っています。

Boot 4 で変わった点（Jackson 2 → 3）

Boot 4.1.1 のドキュメントには「Jackson 3 is the preferred and default library.」とあり、Jackson 2 の対応は非推奨です。@ControllerAdvice などで Jackson の例外クラスを import しているコードは、Boot 4 に上げるとパッケージ名の変更でコンパイルできなくなります。移行の全体は関連記事「Spring Boot 4移行の手順｜3から4の変更点一覧とチェックリスト」で扱っています。

400 と分かりやすいメッセージを返す（@RestControllerAdvice）

既定のままだと、400 の本文は次の形で、理由が分かりません（server.error.include-message の既定が never のため）。

{"timestamp":"2026-10-13T00:00:00.000Z","status":400,"error":"Bad Request","path":"/api/users"}

ResponseEntityExceptionHandler を継承して handleHttpMessageNotReadable を上書きすると、ProblemDetail（RFC 9457 のエラー形式）で項目名と理由を返せます。

package com.example.demo;

import java.util.Arrays;
import java.util.stream.Collectors;

import org.jspecify.annotations.Nullable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageConversionException;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import tools.jackson.core.JacksonException;
import tools.jackson.databind.exc.InvalidFormatException;
import tools.jackson.databind.exc.MismatchedInputException;
import tools.jackson.databind.exc.ValueInstantiationException;

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);

    @Override
    protected @Nullable ResponseEntity<Object> handleHttpMessageNotReadable(
            HttpMessageNotReadableException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {

        Throwable cause = ex.getCause();
        // ログには Jackson の全文（項目の場所・バイト位置つき）を残す
        log.warn("Request body could not be read: {}", cause != null ? cause.getMessage() : ex.getMessage());

        ProblemDetail body = ProblemDetail.forStatusAndDetail(status, toUserMessage(cause));
        body.setTitle("リクエストの本文を読み取れません");
        if (cause instanceof JacksonException jex && !jex.getPath().isEmpty()) {
            body.setProperty("field", path(jex));
        }
        return handleExceptionInternal(ex, body, headers, status, request);
    }

    // 抽象クラスを受け取ろうとした等の「作りの誤り」は 500 のまま、ログに残す
    @ExceptionHandler(HttpMessageConversionException.class)
    ProblemDetail handleConversion(HttpMessageConversionException ex) {
        log.error("Message conversion failed", ex);
        return ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    }

    static String toUserMessage(@Nullable Throwable cause) {
        if (cause instanceof InvalidFormatException ex) {
            String field = path(ex);
            Class<?> target = ex.getTargetType();
            if (target != null && target.isEnum()) {
                String allowed = Arrays.stream(target.getEnumConstants())
                        .map(Object::toString).collect(Collectors.joining(", "));
                return field + " は " + allowed + " のいずれかで指定します（送られた値: " + ex.getValue() + "）";
            }
            return field + " の形式が正しくありません（送られた値: " + ex.getValue() + "）";
        }
        if (cause instanceof ValueInstantiationException ex && ex.getCause() != null) {
            return ex.getCause().getMessage();
        }
        if (cause instanceof MismatchedInputException ex && !ex.getPath().isEmpty()) {
            return path(ex) + " の型が正しくありません";
        }
        if (cause instanceof JacksonException) {
            return "JSON の書き方が正しくありません";
        }
        return "リクエストの本文がありません";
    }

    // [items, 1, qty] → items[1].qty
    static String path(JacksonException ex) {
        StringBuilder sb = new StringBuilder();
        for (JacksonException.Reference ref : ex.getPath()) {
            if (ref.getPropertyName() != null) {
                if (!sb.isEmpty()) sb.append('.');
                sb.append(ref.getPropertyName());
            }
            else if (ref.getIndex() >= 0) {
                sb.append('[').append(ref.getIndex()).append(']');
            }
        }
        return sb.toString();
    }
}

toUserMessage と path の部分は、Jackson 3.1.5 で実際に例外を起こして結果を確かめました。

返る本文の例です。

{
  "type": "about:blank",
  "title": "リクエストの本文を読み取れません",
  "status": 400,
  "detail": "items[1].qty の形式が正しくありません（送られた値: two）",
  "instance": "/api/orders",
  "field": "items[1].qty"
}

ex.getMessage() や Jackson の全文をそのまま返さないようにします。 クラス名（com.example.demo.…）や内部の構造が外に見えるためです。全文はログにだけ出します。

コードの要点

設定だけで ProblemDetail にする

自分でハンドラーを書かない場合でも、次の設定で ProblemDetail 形式になります（Boot 4.1.1 の spring.mvc.problemdetails.enabled、既定は false）。

spring:
  mvc:
    problemdetails:
      enabled: true

このとき HttpMessageNotReadableException の detail は、Spring Framework 7.0.9 のソースでは Failed to read request という固定の文です。messages.properties に problemDetail.org.springframework.http.converter.HttpMessageNotReadableException=リクエストの本文を読み取れません と書くと、文を差し替えられます（Spring Framework のドキュメントの「Customization」）。自分で ResponseEntityExceptionHandler の Bean を作ると、Boot 側のハンドラーは作られません（@ConditionalOnMissingBean）。

例外処理の全体の設計は関連記事「Spring Boot例外処理｜@ControllerAdvice完全版」で扱っています。エラー形式の決め方は関連記事「APIエラーレスポンス設計｜RFC 9457準拠のJSON例と実装コード」で扱っています。

テストで確かめる（MockMvc）

@WebMvcTest(UserController.class)
@Import(ApiExceptionHandler.class)
class UserControllerTest {

    @Autowired MockMvc mvc;

    @Test
    void enumに無い値は400で項目名を返す() throws Exception {
        mvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {"name":"a","status":"DELETED"}
                    """))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.field").value("status"));
    }

    @Test
    void 本文が空なら400() throws Exception {
        mvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isBadRequest());
    }
}

テストの書き方は関連記事「Spring Bootテスト入門｜@WebMvcTestとMockMvcの使い分け」で扱っています。

原因を絞り込む手順

1. ログの JSON parse error: の後ろの書き出しを、冒頭の表で引く
2. 項目が分からなければ、ex.getCause().getMessage() をログに出して reference chain を見る
3. 送られた本文を見る（ブラウザの開発者ツール、または curl -v で送り直す）
4. Boot 4 に上げた直後なら、record のプリミティブ型とJSON の後ろの余計な値を疑う
5. Type definition error なら 500。送る側ではなく、受け取るクラス（抽象クラス・内部クラス）を直す

curl -i -X POST http://localhost:8080/api/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"山田","age":30}'

よくある質問

Q. Boot 3 から Boot 4 に上げたら、今まで通っていた JSON が 400 になりました。 A. ログが Cannot map `null` into type `int` なら、record やコンストラクタの int・boolean の項目が省略されています。Jackson 3 で既定が変わった点です。ラッパー型（Integer・Boolean）にするか、spring.jackson.deserialization.fail-on-null-for-primitives=false にします。

Q. ログに項目名が出ません。 A. Spring のログは Jackson の getOriginalMessage() を使うため、(through reference chain: …) の部分が出ません。上の @RestControllerAdvice のように ex.getCause().getMessage() をログに出すと、項目名とバイト位置が分かります。

Q. JsonParseException を catch するコードが Boot 4 でコンパイルできません。 A. Jackson 3 では tools.jackson.core.exc.StreamReadException です。型の誤りは tools.jackson.databind.exc.MismatchedInputException、全体の親は tools.jackson.core.JacksonException です。

Q. 本文をログに全部出して調べたいです。 A. 開発中だけにします。パスワードや個人情報が入ることがあるためです。フィルターで読むときは ContentCachingRequestWrapper で包み、読んだ後でもコントローラーが本文を受け取れるようにします。

まとめ

• JSON parse error: の後ろは Jackson の文そのまま。書き出しで原因が決まる
• Required request body is missing は本文が空。Spring が出す文
• Boot 4 は Jackson 3（tools.jackson）。record のプリミティブ型の省略とJSON の後ろの余計な値が、新しくエラーになる
• 日付は ISO 形式。それ以外は @JsonFormat（注釈は com.fasterxml.jackson.annotation のまま）
• Type definition error は 500。受け取るクラスの作りを直す
• 利用者には項目名と理由だけを ProblemDetail で返し、Jackson の全文はログへ

参考・出典

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

• Spring Framework リファレンス「Error Responses」：https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
• Spring Boot リファレンス「JSON」：https://docs.spring.io/spring-boot/reference/features/json.html
• Spring Boot リファレンス「Servlet Web Applications」（Error Handling）：https://docs.spring.io/spring-boot/reference/web/servlet.html
• Spring Framework ソースコード（v7.0.9）AbstractJacksonHttpMessageConverter：https://github.com/spring-projects/spring-framework/blob/v7.0.9/spring-web/src/main/java/org/springframework/http/converter/AbstractJacksonHttpMessageConverter.java
• Spring Framework ソースコード（v7.0.9）RequestResponseBodyMethodProcessor：https://github.com/spring-projects/spring-framework/blob/v7.0.9/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestResponseBodyMethodProcessor.java
• Spring Framework ソースコード（v7.0.9）ResponseEntityExceptionHandler：https://github.com/spring-projects/spring-framework/blob/v7.0.9/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.java
• Spring Boot ソースコード（v4.1.1）JacksonProperties：https://github.com/spring-projects/spring-boot/blob/v4.1.1/module/spring-boot-jackson/src/main/java/org/springframework/boot/jackson/autoconfigure/JacksonProperties.java
• jackson-databind ソースコード（3.1.5）DeserializationFeature：https://github.com/FasterXML/jackson-databind/blob/jackson-databind-3.1.5/src/main/java/tools/jackson/databind/DeserializationFeature.java
• RFC 8259 The JavaScript Object Notation (JSON) Data Interchange Format：https://www.rfc-editor.org/rfc/rfc8259
• RFC 9457 Problem Details for HTTP APIs：https://www.rfc-editor.org/rfc/rfc9457

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