Introduction

Jackson's default behavior throws UnrecognizedPropertyException when it encounters JSON properties that don't have matching fields in the target Java class. This commonly happens when APIs evolve and add new fields, or when deserializing responses from third-party APIs.

This error is particularly frustrating because it breaks backward compatibility -- adding a field to an API response breaks all existing consumers.

Symptoms

  • Jackson throws "UnrecognizedPropertyException: Unrecognized field X (class Y), not marked as ignorable"
  • Deserialization fails after an API adds new fields to its response
  • Only specific JSON payloads fail while others deserialize successfully

Common Causes

  • JSON response contains fields not defined in the target Java class
  • API added new optional fields that existing consumers don't know about
  • Typo in JSON property name or Java field name causes mismatch

Step-by-Step Fix

  1. 1.Configure ObjectMapper to ignore unknown properties: Set the global deserialization feature.
  2. 2.```java
  3. 3.import com.fasterxml.jackson.databind.ObjectMapper;
  4. 4.import com.fasterxml.jackson.databind.DeserializationFeature;

ObjectMapper mapper = new ObjectMapper(); mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

// Now unknown properties are silently ignored User user = mapper.readValue(json, User.class); ```

  1. 1.Use @JsonIgnoreProperties at class level: Ignore unknown properties for a specific class.
  2. 2.```java
  3. 3.import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true) public class User { private String name; private String email; // New fields in API response are ignored } ```

  1. 1.Use JsonAnySetter to capture unknown properties: Collect unknown properties for debugging or forwarding.
  2. 2.```java
  3. 3.import com.fasterxml.jackson.annotation.JsonAnySetter;
  4. 4.import com.fasterxml.jackson.annotation.JsonAnyGetter;
  5. 5.import java.util.HashMap;
  6. 6.import java.util.Map;

public class User { private String name; private Map<String, Object> unknownProperties = new HashMap<>();

@JsonAnySetter public void setUnknownProperty(String key, Object value) { unknownProperties.put(key, value); }

@JsonAnyGetter public Map<String, Object> getUnknownProperties() { return unknownProperties; } } ```

  1. 1.Set Jackson configuration globally in Spring Boot: Configure through application properties.
  2. 2.```yaml
  3. 3.# application.yml:
  4. 4.spring:
  5. 5.jackson:
  6. 6.deserialization:
  7. 7.fail-on-unknown-properties: false
  8. 8.`

Prevention

  • Set FAIL_ON_UNKNOWN_PROPERTIES to false globally for external API responses
  • Use @JsonIgnoreProperties(ignoreUnknown = true) on all DTO classes
  • Use JsonAnySetter to detect when APIs add new unexpected fields
  • Version your API contracts and update DTO classes when APIs evolve