Home โบ Java exceptions โบ UnrecognizedPropertyException
UnrecognizedPropertyException: causes and fixes
Jackson found a JSON field that has no matching property in the target Java class.
What it looks like
com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field "nickname" (class com.acme.User), not marked as ignorable (3 known properties: "id", "name", "email"])Extends JsonMappingException in com.fasterxml.jackson.databind.exc.
What it means
Jackson maps JSON fields to Java properties by name. When the JSON contains a field the class does not have, and the ObjectMapper is configured to fail on unknown properties (its default when you create a plain new ObjectMapper()), it throws this exception, naming the field and listing the known properties. It is typical when an API adds a field and an older client class is not updated. Spring Boot's auto-configured mapper disables the check.
Common causes
- The JSON has a new or renamed field the class does not declare.
- A naming mismatch: snake_case JSON against camelCase Java without a naming strategy or
@JsonProperty. - A plain
new ObjectMapper()used instead of the Spring-configured bean. - Getters or setters missing, so the property is not recognised.
How to fix it
- Add the property to the class, or map it with
@JsonProperty("name"). - Tolerate extra fields with
@JsonIgnoreProperties(ignoreUnknown = true)on the class. - Configure the mapper:
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false). - Inject Spring's ObjectMapper rather than creating your own, so global settings apply.
Broken and fixed
ObjectMapper m = new ObjectMapper();
m.readValue(json, User.class); // fails on unknown "nickname"@JsonIgnoreProperties(ignoreUnknown = true)
public record User(long id, String name, String email) {}๐ Unravel the failing code ๐ Unravel the fix
Debug it faster
Paste the whole stack trace into the stack trace beautifier to hide framework frames, jump to the root cause and find the first line of your own code. It runs in your browser, so the trace never leaves your machine.
Frequently asked questions
Is UnrecognizedPropertyException a checked or unchecked exception?
UnrecognizedPropertyException is a checked exception (it extends JsonMappingException), so the compiler forces you to catch it or declare it with throws.
Which package is UnrecognizedPropertyException in?
It lives in com.fasterxml.jackson.databind.exc, so the import is import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException;.
What is the first thing to check when I see UnrecognizedPropertyException?
Read the message and the first stack trace line in your own code. The usual causes are: The JSON has a new or renamed field the class does not declare; and A naming mismatch: snake_case JSON against camelCase Java without a naming strategy or @JsonProperty.