JAVA Jackson 역직렬화 오류가 발생하는 원인과 해결 방법

Jackson 역직렬화 오류가 발생하는 원인을 생성자, 기본 생성자, JSON 필드 불일치, 타입 변환, 날짜 형식, enum, record, Lombok 사례로 나누어 설명하고, Spring Boot 환경에서 자주 발생하는 Jackson 오류의 해결 방법과 디버깅 순서를 정리합니다.

Jackson 직렬화와 역직렬화의 차이

먼저 Jackson이 어떤 작업을 수행하는지 이해하시면 오류 원인을 찾기가 훨씬 쉬워집니다.

직렬화는 Java 객체를 JSON으로 변환하는 과정입니다.

예를 들어 Java 객체에 name과 age 값이 있다면 이를 JSON 형태로 변환하여 API 응답으로 전달할 수 있습니다.

반대로 역직렬화는 JSON 데이터를 Java 객체로 변환하는 과정입니다.

클라이언트에서 전달한 JSON 요청을 Spring Boot의 DTO 객체로 변환하는 과정이 대표적인 Jackson 역직렬화입니다.

구분변환 방향대표적인 사용 사례

직렬화	Java 객체 → JSON	REST API 응답
역직렬화	JSON → Java 객체	REST API 요청
주요 처리 도구	ObjectMapper	직접 JSON 변환
Spring Boot 적용	자동 처리	@RequestBody 사용

Spring Boot에서 @RequestBody를 사용하면 내부적으로 HTTP 요청 본문의 JSON을 Java 객체로 변환합니다. 이 과정에서 JSON 구조와 DTO 구조가 맞지 않으면 Jackson 오류가 발생할 수 있습니다.

Jackson 역직렬화 오류가 발생하는 대표적인 원인

Jackson 역직렬화 오류는 여러 형태로 나타나지만, 실무에서 확인해야 할 부분은 크게 몇 가지로 나눌 수 있습니다.

• 기본 생성자가 없을 수 있습니다.
• JSON 필드명과 Java 필드명이 다를 수 있습니다.
• JSON 값과 Java 필드 타입이 일치하지 않을 수 있습니다.
• 배열과 객체 구조를 반대로 선언했을 수 있습니다.
• 날짜와 시간 형식이 맞지 않을 수 있습니다.
• enum에 정의되지 않은 값이 전달될 수 있습니다.
• 알 수 없는 JSON 필드가 추가될 수 있습니다.
• record 또는 불변 객체의 생성 조건이 맞지 않을 수 있습니다.

예외 메시지 전체를 처음부터 읽기보다 예외 클래스 이름과 메시지의 핵심 부분을 먼저 확인하는 방식이 효율적입니다.

기본 생성자가 없어서 발생하는 오류

Cannot construct instance 오류를 확인하셔야 합니다

Jackson 역직렬화 과정에서 자주 만나는 메시지 중 하나가 Cannot construct instance of입니다.

Jackson이 JSON 데이터를 객체로 만들려면 객체를 생성할 방법을 알아야 합니다. 일반적인 DTO에서는 매개변수가 없는 기본 생성자를 사용한 뒤 각 필드에 값을 매핑하는 방식이 사용될 수 있습니다.

기본 생성자가 없고 Jackson이 사용할 수 있는 생성자 정보도 충분하지 않다면 객체를 만들지 못할 수 있습니다.

특히 다음과 같은 상황을 확인하셔야 합니다.

• 매개변수가 있는 생성자만 존재하는 경우입니다.
• 기본 생성자를 직접 작성하지 않은 경우입니다.
• Lombok의 @AllArgsConstructor만 사용한 경우입니다.
• 불변 객체의 생성 방법을 Jackson이 알 수 없는 경우입니다.

일반적인 DTO라면 기본 생성자를 제공하는 방식으로 해결할 수 있습니다. Lombok을 사용한다면 @NoArgsConstructor 적용 여부를 확인하시면 됩니다.

다만 모든 클래스에 기본 생성자를 추가하는 것이 항상 최선은 아닙니다. 불변 객체나 생성자를 통한 검증이 필요한 객체라면 @JsonCreator와 @JsonProperty를 사용하여 Jackson이 어떤 생성자를 호출해야 하는지 명시하는 방법이 더 적절할 수 있습니다.

JSON 필드명과 Java 필드명이 다른 경우

@JsonProperty로 이름을 연결할 수 있습니다

JSON에서는 user_name을 사용하지만 Java DTO에서는 userName을 사용하는 경우가 있습니다.

Jackson의 기본 설정만으로 이름이 자동 연결되지 않는 환경이라면 JSON 값이 필드에 들어가지 않거나 예상하지 못한 필드 오류가 발생할 수 있습니다.

이럴 때는 @JsonProperty를 사용하여 JSON 필드명과 Java 필드명을 명시적으로 연결할 수 있습니다.

예를 들어 외부 API가 스네이크 케이스를 사용하고 내부 Java 코드가 카멜 케이스를 사용한다면 다음 사항을 검토하시면 됩니다.

• 개별 필드에 @JsonProperty를 지정할 수 있습니다.
• ObjectMapper의 네이밍 전략을 설정할 수 있습니다.
• Spring Boot의 Jackson 설정에서 네이밍 정책을 통일할 수 있습니다.

필드가 몇 개 되지 않는다면 개별 매핑도 괜찮지만, 프로젝트 전체에서 동일한 규칙을 사용한다면 전역 네이밍 전략을 적용하는 편이 유지보수에 유리할 수 있습니다.

존재하지 않는 JSON 필드 때문에 발생하는 오류

UnrecognizedPropertyException을 확인하셔야 합니다

클라이언트가 Java DTO에 없는 필드를 추가로 보내면 설정에 따라 UnrecognizedPropertyException이 발생할 수 있습니다.

예를 들어 DTO에는 name과 age만 있는데 JSON에 address가 추가되어 있다면 Jackson이 해당 필드를 처리하지 못할 수 있습니다.

해결 방법은 상황에 따라 달라집니다.

• DTO에 필요한 필드를 추가할 수 있습니다.
• 불필요한 필드는 JSON 요청에서 제거할 수 있습니다.
• 특정 클래스에서 알 수 없는 필드를 무시하도록 설정할 수 있습니다.
• ObjectMapper 전역 설정을 변경할 수 있습니다.

외부 API처럼 응답 필드가 자주 추가될 가능성이 있다면 알 수 없는 필드를 무시하는 전략이 유용할 수 있습니다. 반대로 내부 API에서 요청 형식을 엄격하게 검증해야 한다면 무조건 무시하기보다 오류를 발생시키는 편이 적절할 수 있습니다.

알 수 없는 필드를 무조건 무시하면 클라이언트의 오타도 발견하지 못할 수 있으므로 API 성격에 맞게 선택하셔야 합니다.

JSON 값과 Java 타입이 맞지 않는 경우

MismatchedInputException과 InvalidFormatException을 확인하셔야 합니다

JSON에서는 문자열을 전달했는데 Java 필드는 숫자형으로 선언되어 있거나, 객체를 전달했는데 문자열 필드로 받으려고 하면 역직렬화 오류가 발생할 수 있습니다.

대표적인 사례는 다음과 같습니다.

JSON 값Java 필드발생 가능성

"100"	Integer	설정과 값에 따라 변환될 수 있습니다
"abc"	Integer	변환 오류가 발생할 수 있습니다
{...}	String	구조 불일치 오류가 발생할 수 있습니다
[...]	일반 객체	배열과 객체 불일치 오류가 발생할 수 있습니다
null	기본형 int	null 처리 문제가 발생할 수 있습니다

특히 API 요청에서는 숫자처럼 보이는 문자열과 실제 숫자를 구분해야 합니다.

JSON의 100과 "100"은 같은 값처럼 보이지만 타입은 다릅니다. 프런트엔드에서 폼 입력값을 그대로 전송하면 숫자 입력값도 문자열로 전달될 수 있으므로 실제 요청 데이터를 확인하셔야 합니다.

또한 null 가능성이 있는 값은 Java 기본형보다 래퍼 클래스를 사용하는 것이 적절할 수 있습니다.

예를 들어 int는 null을 표현할 수 없지만 Integer는 null을 가질 수 있습니다. 선택 입력값이라면 이러한 차이가 Jackson 역직렬화 결과에 영향을 줄 수 있습니다.

배열과 객체 구조가 다른 경우

JSON 구조를 잘못 이해하면 MismatchedInputException과 같은 Jackson 오류가 발생할 수 있습니다.

클라이언트가 배열을 전송하는데 서버에서는 단일 객체로 받거나, 단일 객체를 전송하는데 List로 받는 경우가 대표적입니다.

다음 두 구조는 완전히 다릅니다.

• { ... } 형태는 하나의 객체입니다.
• [ ... ] 형태는 배열입니다.

API 요청이 여러 건의 데이터를 전달한다면 List<DTO>와 같은 컬렉션 타입이 필요할 수 있습니다. 반대로 단일 JSON 객체라면 DTO 하나로 받아야 합니다.

예외 메시지에 START_ARRAY 또는 START_OBJECT가 보인다면 JSON의 배열과 객체 구조부터 확인하시는 것이 좋습니다.

프런트엔드 코드만 보고 판단하지 마시고 브라우저 개발자 도구의 Network 탭이나 실제 HTTP 요청 로그에서 전송된 JSON 본문을 확인하시면 원인을 더 빠르게 찾을 수 있습니다.

날짜와 시간 형식이 맞지 않는 경우

LocalDate와 LocalDateTime 형식을 확인하셔야 합니다

날짜 관련 Jackson 오류도 자주 발생합니다.

Java 필드가 LocalDate인데 JSON에서는 날짜와 시간을 함께 보내거나, LocalDateTime 필드에 프로젝트에서 기대하지 않는 형식이 들어오면 변환에 실패할 수 있습니다.

예를 들어 다음 항목을 확인하셔야 합니다.

• 날짜 구분자가 예상한 형식과 같은지 확인하셔야 합니다.
• 시간 정보가 필요한 타입인지 확인하셔야 합니다.
• 타임존 정보가 포함되어 있는지 확인하셔야 합니다.
• 프런트엔드와 백엔드의 날짜 형식이 같은지 확인하셔야 합니다.

프로젝트에서 특정 날짜 형식을 사용한다면 @JsonFormat으로 형식을 명시할 수 있습니다.

다만 DTO마다 서로 다른 형식을 무분별하게 지정하면 관리가 어려워질 수 있습니다. 서비스 전체에서 날짜 규칙이 정해져 있다면 ObjectMapper 설정과 API 명세를 함께 통일하는 편이 좋습니다.

enum 값이 일치하지 않는 경우

Java enum 필드에 정의되지 않은 문자열이 들어오면 InvalidFormatException이 발생할 수 있습니다.

예를 들어 enum에는 ACTIVE와 INACTIVE만 정의되어 있는데 JSON에서 active 또는 UNKNOWN이 전달되면 문제가 발생할 수 있습니다.

이 경우 다음 내용을 확인하셔야 합니다.

• 대문자와 소문자가 정확히 일치하는지 확인하셔야 합니다.
• enum에 실제 요청값이 정의되어 있는지 확인하셔야 합니다.
• 외부 값과 내부 enum 값의 이름이 다른지 확인하셔야 합니다.
• 알 수 없는 값을 어떻게 처리할지 정책을 정하셔야 합니다.

외부 API 값과 Java enum 이름이 다르다면 별도의 변환 로직을 두는 것이 좋습니다. 단순히 모든 값을 문자열로 받으면 오류는 줄어들 수 있지만, 타입 안정성과 검증의 장점을 잃을 수 있습니다.

enum 오류는 Jackson 설정만 변경하기보다 허용 가능한 값의 범위를 API 계약에서 명확하게 관리하는 것이 중요합니다.

Lombok을 사용할 때 발생하는 Jackson 오류

Lombok은 DTO 코드를 줄이는 데 편리하지만 생성자 조합에 따라 Jackson 역직렬화 오류의 원인이 될 수 있습니다.

특히 다음 조합을 확인하셔야 합니다.

• @Data만 사용한 경우입니다.
• @Builder를 추가한 경우입니다.
• @AllArgsConstructor만 존재하는 경우입니다.
• final 필드가 포함된 경우입니다.
• 기본 생성자가 필요한 구조인데 생성되지 않은 경우입니다.

@Builder를 사용했다고 해서 Jackson이 자동으로 해당 빌더를 사용하여 역직렬화하는 것은 아닐 수 있습니다. 프로젝트의 Lombok과 Jackson 사용 방식에 따라 별도의 설정이나 애노테이션이 필요할 수 있습니다.

따라서 오류가 발생하면 Lombok 애노테이션을 한꺼번에 추가하기보다 실제로 컴파일된 클래스에 어떤 생성자와 접근자가 만들어지는지 확인하시는 것이 중요합니다.

DTO가 단순한 요청 데이터 객체라면 필요한 생성자와 접근 방식을 명확하게 구성하는 편이 문제를 줄이는 데 도움이 됩니다.

Java record에서 Jackson 역직렬화를 사용할 때 확인할 점

Java record는 데이터 전달 객체를 간결하게 작성할 수 있어 DTO에 많이 활용됩니다.

record는 일반 클래스와 생성 방식이 다르므로 기본 생성자를 추가하는 방식으로 접근해서는 안 됩니다. Jackson이 record의 구성 요소와 생성자를 기준으로 값을 연결할 수 있는 환경인지 확인하셔야 합니다.

record를 사용할 때는 다음 사항을 점검하시면 됩니다.

• 프로젝트에서 사용하는 Jackson 버전과 환경을 확인하셔야 합니다.
• JSON 필드명과 record 구성 요소 이름이 일치하는지 확인하셔야 합니다.
• 필요한 경우 @JsonProperty를 적용하셔야 합니다.
• null 허용 여부와 기본값 처리 방식을 확인하셔야 합니다.

Spring Boot에서 Java record를 DTO로 사용한다면 일반 클래스와 동일한 방식으로 무조건 기본 생성자를 찾기보다 record의 생성자 매핑 구조를 먼저 확인하시는 것이 좋습니다.

중첩 객체에서 발생하는 역직렬화 오류

JSON 안에 객체가 다시 포함되어 있다면 내부 DTO 구조도 정확하게 일치해야 합니다.

예를 들어 사용자 정보 안에 주소 객체가 포함되어 있다면 Java에서도 주소를 표현하는 객체 구조가 필요할 수 있습니다.

중첩 객체 오류는 최상위 DTO만 보면 원인을 찾기 어려운 경우가 많습니다. 예외 메시지의 through reference chain 부분을 확인하면 어떤 필드를 따라가다가 오류가 발생했는지 파악하는 데 도움이 됩니다.

다음과 같은 경로가 보인다면 마지막 필드부터 확인하시면 됩니다.

RequestDTO → user → address → zipCode

이 경우 요청 객체 전체를 수정하기보다 zipCode의 실제 JSON 값과 Java 타입을 먼저 비교하시는 것이 효율적입니다.

Jackson 오류 메시지의 참조 경로는 실제 문제가 발생한 필드 위치를 찾는 중요한 단서입니다.

ObjectMapper를 직접 사용할 때 발생하는 오류

Spring Boot의 @RequestBody가 아니라 ObjectMapper를 직접 사용하는 경우에도 동일한 역직렬화 문제가 발생할 수 있습니다.

문자열 JSON을 객체로 변환할 때는 대상 타입 정보가 정확해야 합니다.

단일 객체는 비교적 간단하지만 List<DTO>처럼 제네릭 타입을 변환할 때는 타입 정보가 사라지지 않도록 주의하셔야 합니다.

특히 다음 상황을 확인하셔야 합니다.

• 단일 객체와 리스트를 혼동하지 않았는지 확인하셔야 합니다.
• 제네릭 컬렉션의 실제 타입 정보를 전달했는지 확인하셔야 합니다.
• 서로 다른 ObjectMapper 설정을 사용하고 있지 않은지 확인하셔야 합니다.
• Spring Boot가 관리하는 ObjectMapper와 직접 생성한 인스턴스의 설정 차이를 확인하셔야 합니다.

프로젝트에서 날짜 모듈, 네이밍 전략, 알 수 없는 필드 처리 정책 등을 설정했다면 새로운 ObjectMapper를 직접 생성할 때 해당 설정이 적용되지 않을 수 있습니다.

따라서 특별한 이유가 없다면 프로젝트에서 관리하는 설정과 일관성을 유지하는 것이 좋습니다.

Jackson 오류를 빠르게 찾는 디버깅 순서

Jackson 역직렬화 오류가 발생하면 애노테이션부터 무작정 추가하기보다 일정한 순서로 확인하는 것이 좋습니다.

1. 실제 JSON 요청 본문을 확인하셔야 합니다

프런트엔드 코드에서 예상한 데이터가 아니라 실제 네트워크 요청에 포함된 JSON을 확인하셔야 합니다.

2. 예외 클래스 이름을 확인하셔야 합니다

UnrecognizedPropertyException, InvalidFormatException, MismatchedInputException처럼 예외 종류를 먼저 확인하시면 문제 범위를 줄일 수 있습니다.

3. 예외 메시지의 마지막 필드를 확인하셔야 합니다

through reference chain에 표시된 경로를 따라가면 실제 문제가 발생한 필드를 찾을 수 있습니다.

4. JSON 구조와 DTO 구조를 비교하셔야 합니다

객체, 배열, 중첩 객체의 구조가 일치하는지 확인하셔야 합니다.

5. 값과 Java 타입을 비교하셔야 합니다

문자열, 숫자, boolean, 날짜, enum, null 값을 각각 확인하셔야 합니다.

6. 생성자와 Jackson 애노테이션을 확인하셔야 합니다

기본 생성자, @JsonCreator, @JsonProperty, Lombok 설정을 확인하셔야 합니다.

7. ObjectMapper 설정을 확인하셔야 합니다

전역 설정과 직접 생성한 ObjectMapper 사이에 차이가 있는지 살펴보셔야 합니다.

이 순서로 확인하면 원인과 관계없는 코드를 수정하는 일을 줄일 수 있습니다.

Jackson 오류별로 확인할 항목 정리

오류 또는 메시지우선 확인할 내용대표적인 해결 방향

Cannot construct instance	생성자	기본 생성자 또는 생성자 매핑을 확인합니다
UnrecognizedPropertyException	존재하지 않는 필드	DTO 또는 알 수 없는 필드 정책을 확인합니다
MismatchedInputException	JSON 구조	객체와 배열 구조를 비교합니다
InvalidFormatException	데이터 타입	숫자, 날짜, enum 값을 확인합니다
START_ARRAY	배열 전달 여부	List 타입 필요 여부를 확인합니다
START_OBJECT	객체 전달 여부	DTO 구조를 확인합니다
through reference chain	오류 발생 경로	마지막 필드부터 추적합니다

예외 이름만 보고 해결 방법을 단정해서는 안 됩니다. 같은 예외라도 실제 원인은 JSON 구조, 필드 타입, 생성 방식에 따라 달라질 수 있으므로 오류 메시지와 실제 요청 데이터를 함께 확인하셔야 합니다.

Jackson 역직렬화 문제를 예방하는 방법

오류가 발생할 때마다 DTO에 애노테이션을 추가하는 방식은 장기적으로 관리하기 어렵습니다.

먼저 API 요청과 응답 구조를 명확하게 구분하는 것이 좋습니다. 엔티티를 그대로 요청 객체로 사용하기보다 API 목적에 맞는 DTO를 사용하면 예상하지 못한 필드 매핑 문제를 줄일 수 있습니다.

프런트엔드와 백엔드 사이의 타입 규칙도 통일하셔야 합니다. 숫자, boolean, 날짜, enum 값을 어떤 형식으로 주고받을지 정해 두면 변환 오류를 예방하는 데 도움이 됩니다.

또한 Jackson 전역 설정을 변경할 때는 영향 범위를 확인하셔야 합니다. 알 수 없는 필드를 모두 무시하거나 타입 변환을 지나치게 허용하면 당장의 오류는 사라질 수 있지만 잘못된 요청을 늦게 발견할 가능성이 있습니다.

가장 좋은 해결 방법은 오류를 숨기는 설정이 아니라 JSON과 Java 객체의 계약을 명확하게 맞추는 것입니다.

마무리

Jackson 역직렬화 오류가 발생하는 원인과 해결 방법을 정리하면 핵심은 JSON 구조, Java 객체 생성 방식, 필드 타입의 일치 여부를 확인하는 것입니다.

Cannot construct instance가 나타나면 생성자를 확인하시고, UnrecognizedPropertyException이 발생하면 JSON 필드와 DTO를 비교하셔야 합니다. MismatchedInputException이 보이면 배열과 객체 구조를 살펴보시고, InvalidFormatException이 발생하면 숫자, 날짜, enum과 같은 실제 값의 타입을 확인하시면 됩니다.

Spring Boot에서 발생하는 Jackson 오류는 예외 메시지가 길지만 대부분 실제 문제가 발생한 필드 경로를 포함하고 있습니다. 따라서 설정을 무작정 변경하기보다 실제 요청 JSON 확인 → 예외 종류 확인 → 참조 경로 추적 → DTO 구조와 타입 비교 순서로 접근하시는 것이 가장 효율적입니다.

FAQ

Jackson 직렬화와 역직렬화는 무엇이 다른가요?

직렬화는 Java 객체를 JSON으로 변환하는 과정이며, 역직렬화는 JSON을 Java 객체로 변환하는 과정입니다. Spring Boot에서 API 응답을 JSON으로 만드는 과정은 직렬화에 해당하며, @RequestBody의 JSON을 DTO로 변환하는 과정은 역직렬화에 해당합니다.

Cannot construct instance 오류는 왜 발생하나요?

Jackson이 대상 객체를 생성할 방법을 찾지 못할 때 발생할 수 있습니다. 기본 생성자 유무, 매개변수 생성자, @JsonCreator, @JsonProperty, Lombok 생성자 설정을 확인하셔야 합니다.

@NoArgsConstructor를 추가하면 모든 역직렬화 오류가 해결되나요?

그렇지 않습니다. 기본 생성자가 필요한 일반 DTO에서는 도움이 될 수 있지만, JSON 필드 불일치, 타입 오류, 배열과 객체 구조 차이, 날짜 형식 문제는 별도로 해결하셔야 합니다.

JSON에 DTO에 없는 필드가 있으면 어떻게 해야 하나요?

API 정책에 따라 DTO에 필드를 추가하거나 알 수 없는 필드를 무시하도록 설정할 수 있습니다. 내부 API에서 요청 형식을 엄격하게 관리해야 한다면 무조건 무시하기보다 잘못된 필드를 오류로 처리하는 방식도 검토하셔야 합니다.

MismatchedInputException이 발생하면 무엇부터 확인해야 하나요?

JSON이 객체인지 배열인지 먼저 확인하시는 것이 좋습니다. 그다음 실제 JSON 값의 타입과 Java 필드 타입이 일치하는지 살펴보셔야 합니다.

Lombok의 @Builder를 사용하면 Jackson 역직렬화가 자동으로 처리되나요?

항상 자동으로 처리된다고 볼 수는 없습니다. 클래스의 생성자 구조와 Lombok 및 Jackson 설정에 따라 추가 구성이 필요할 수 있으므로 실제 생성 방식과 프로젝트 환경을 확인하셔야 합니다.

Java record도 Jackson 역직렬화를 사용할 수 있나요?

사용할 수 있지만 프로젝트의 Jackson 환경과 JSON 필드 매핑을 확인하셔야 합니다. 일반 클래스처럼 기본 생성자를 추가하는 방식이 아니라 record의 구성 요소와 생성자 매핑 구조를 기준으로 접근하셔야 합니다.

Jackson 오류를 가장 빠르게 찾는 방법은 무엇인가요?

실제 JSON 요청 본문을 먼저 확인하고 예외 클래스 이름과 through reference chain 경로를 살펴보시는 것이 좋습니다. 이후 JSON 구조, DTO 필드 타입, 생성자 순서로 비교하면 원인을 빠르게 좁힐 수 있습니다.

관련글

• Spring Boot Lombok 실무 사용법: 설치부터 Annotation 적용과 오류 해결까지
• 스프링부트 Playwright로 HTML을 PDF로 변환할 때 500 에러 해결 방법