Skip to content
javahacks.dev
Spring MVC

Fix Jackson Unrecognized Field and Unknown Property Errors

Fix Jackson's Unrecognized field not marked as ignorable error by deciding whether to accept unknown properties, rename a field or fix the client.

6 min read
Summarize in AI
Flat illustration of an object serialised to JSON and read back, with the Spring, YAML and JSON logos.

A request body or a message from another service fails to parse with a message that lists what Jackson expected:

Text
com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field "nickname" (class dev.javahacks.Customer), not marked as ignorable (2 known properties: "id", "name"])

The JSON had a nickname property and Customer has no such property. By default Jackson treats that as an error, so a typo in a client or a new field from a producer does not silently vanish. Whether that is what you want depends on the situation. In Spring Boot 4, Jackson 3 sits underneath and its exception classes live in tools.jackson.databind.exc; the messages and fixes are the same. The web layer reports it as [HttpMessageNotReadableException](/library/httpmessagenotreadableexception-fix-json-parse-error).

Why you see it

Spring Boot's ObjectMapper is configured with FAIL_ON_UNKNOWN_PROPERTIES disabled (spring.jackson.deserialization.fail-on-unknown-properties defaults to false). The error appears when the mapper is not Boot's:

  • A new ObjectMapper() in your own code or a test.
  • A library's internal mapper, for example a Kafka deserializer or a REST client built without Boot's customization.
  • An ObjectMapper bean you defined yourself, replacing the auto-configured one.
  • The property set to true in configuration.

Decide: strict or lenient

ChooseWhen
Strict (fail)You own both sides and want typos caught early
Lenient (ignore)You consume someone else's API, which may add fields over time

Consuming a third-party API strictly means that every new field they add breaks you. Accepting unknown properties follows the "be liberal in what you accept" robustness principle for clients. A public API you serve can stay strict to give feedback to callers.

Fix 1: ignore on one class

java
@JsonIgnoreProperties(ignoreUnknown = true)
public record Customer(long id, String name) {}

The annotation applies to this type only, which is the narrowest change and keeps strictness elsewhere.

Fix 2: configure the mapper

For the whole application:

properties
spring.jackson.deserialization.fail-on-unknown-properties=false

or for a mapper you build:

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

Use Spring's Jackson2ObjectMapperBuilder or the Boot-provided ObjectMapper bean, so you inherit the other defaults (modules, date formats) too. A bare new ObjectMapper() also lacks the Java time module, which causes a different error.

Fix 3: the field is real, so model it

If nickname is part of the contract, add it to the class. If the JSON uses another name, map it:

java
public record Customer(
        long id,
        String name,
        @JsonAlias({"nick", "nickname"}) String displayName) {}

@JsonAlias accepts several incoming names. @JsonProperty("display_name") sets the name used for both reading and writing. A mismatch in naming style (snake_case from the client, camelCase in Java) is better solved globally:

properties
spring.jackson.property-naming-strategy=SNAKE_CASE

Fix 4: capture the extras

When you want to keep unknown fields, for example for pass-through:

java
public class Event {
    public String type;

    private final Map<String, Object> extra = new HashMap<>();

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

    @JsonAnyGetter
    public Map<String, Object> extra() { return extra; }
}

Find the source of the unknown field

The message gives the field name. Search the client code or the producer for it. A typo (nicname) is a client bug; a field added by a newer version of the producer is an API evolution question. Version contracts deliberately; the design rules are in REST API design rules.

The defaults differ by where the mapper comes from

A bare new ObjectMapper() fails on unknown properties, and the mapper that Spring Boot builds does not. A test that constructs its own mapper can fail on JSON that the running application accepts, and the reverse. The behaviour in each place:

MapperUnknown properties
new ObjectMapper()Fails with UnrecognizedPropertyException
The Boot auto-configured mapperIgnored, fail-on-unknown-properties is off
Jackson2ObjectMapperBuilder without BootIgnored, the builder disables the feature
JsonMapper.builder().build()Fails

When the same class parses fine in the application and fails in a unit test, check which mapper each uses. Inject the Spring-configured one into tests, or construct the test mapper with the same settings.

Read tolerantly, write strictly

A consumer of another team's API should ignore fields it does not know, since the producer will add fields without warning, and a strict reader breaks on a harmless change. A producer should write exactly what its contract says. The pattern is often called the tolerant reader, and it has a limit: ignoring unknown fields on a request your own server receives hides client typos, as covered in the post on message conversion errors.

java
@JsonIgnoreProperties(ignoreUnknown = true)
public record PartnerOrder(String id, BigDecimal total) { }

Apply the annotation to the types that read outside data, and leave it off the types that read your own clients' requests, so that a misspelt field is rejected with a clear message.

Collect what you do not model

When the extra fields carry information you want to keep or pass on, an any-setter stores them in a map:

java
public class Customer {
    public long id;
    public String name;

    private final Map<String, Object> extras = new LinkedHashMap<>();

    @JsonAnySetter
    void extra(String key, Object value) {
        extras.put(key, value);
    }

    @JsonAnyGetter
    public Map<String, Object> extras() {
        return extras;
    }
}

The pair makes a round trip lossless: a field you did not model is read into the map and written back out. Use it for proxies and for documents with a stable core and a free-form edge. It disables the checking that tells you the field exists, so a typo goes unnoticed in this class.

Detect the change before it breaks production

An unknown field is a signal that the producer changed, and you can learn it from a test that fails on it, in CI, against a recorded sample of the real payload:

java
@Test
void sampleHasNoUnknownFields() throws Exception {
    ObjectMapper strict = new ObjectMapper().enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
    try (InputStream in = getClass().getResourceAsStream("/samples/partner-order.json")) {
        assertDoesNotThrow(() -> strict.readValue(in, PartnerOrder.class));
    }
}

Refresh the sample when the partner publishes a new version. The failing test is a notice that the type is behind the contract, and it arrives at review time, before a message is dropped. Production keeps the lenient mapper, so a surprise field costs nothing at runtime.

Where the field came from

Source of the unknown fieldFix
The producer added a fieldModel it if you need it, ignore it if not
A typo in your own clientFix the client, keep the strict mapper on the endpoint
A renamed fieldUse @JsonAlias to accept both names during a migration
A field only in some responsesMake it optional, with a default
A different class version on each sideAlign the versions or add a version field

@JsonAlias({"nick", "nickname"}) is the tool for a rename in flight, since it lets a consumer accept the old and the new name during the overlap while the producer is upgraded.

Where this does not apply

If the error is Cannot construct instance, the type has no usable constructor: that fix. Security-sensitive endpoints may prefer strict parsing, so that an attacker's extra properties (for example isAdmin) are rejected instead of bound. The Jackson annotations documentation and the Spring Boot Jackson properties are the primary references.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.