阅读中文版本

Jackson UnrecognizedPropertyException — Unknown JSON Field

Fix Jackson UnrecognizedPropertyException by configuring FAIL_ON_UNKNOWN_PROPERTIES, adding @JsonIgnoreProperties, or matching the field names.

jshell -q <<'EOF'
var m = new com.fasterxml.jackson.databind.ObjectMapper();
try { m.readValue("{\"a\":1,\"b\":2}", java.util.Map.class); } catch (Exception e) { System.out.println(e.getClass()); }
EOF

m.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

Symptoms

When you hit “Jackson UnrecognizedPropertyException — Unknown JSON Field”, guessing wastes time. The guide below follows evidence: reproduce the symptom, run targeted diagnostics, identify the root cause, apply the fix, and verify it with concrete checks.

Observed symptoms include:

• com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field “x”
• Parsing fails when the API adds a new field
• The error names a field that seems unimportant

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Reproduce with the raw payload

jshell -q <<'EOF'
var m = new com.fasterxml.jackson.databind.ObjectMapper();
try { m.readValue("{\"a\":1,\"b\":2}", java.util.Map.class); } catch (Exception e) { System.out.println(e.getClass()); }
EOF

A concrete failure with the payload shows which field the class does not declare.

Step 2: Choose tolerant or explicit mapping

m.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

Disabling the strict check tolerates extra fields; annotating fields keeps strictness where wanted.

Likely contributors, in order of frequency:

• The JSON contains a field absent from the target class and the mapper is strict
• Field names differ in case or use snake_case while the class expects camelCase
• An ignored or renamed property is not annotated with @JsonIgnoreProperties/@JsonProperty

Root Cause

Jackson fails on unknown properties when FAIL_ON_UNKNOWN_PROPERTIES is enabled (the default). Any JSON field not mapped to a class member therefore aborts deserialization with UnrecognizedPropertyException.

The Fix

Either disable FAIL_ON_UNKNOWN_PROPERTIES globally for forward compatibility, annotate the class with @JsonIgnoreProperties(ignoreUnknown = true), or add the missing field and map names with @JsonProperty.

Watch out: Ignoring unknown properties can hide typos in field names; keep FAIL_ON_UNKNOWN in tests that assert the contract.

@JsonIgnoreProperties(ignoreUnknown = true) // tolerate new fields
public class User {
    @JsonProperty("user_id") // map snake_case
    private long id;
    private String name;
    // getters/setters
}

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

Verify and Prevent

Reparse the same payload and confirm success; add a test asserting the known fields are populated, and keep one test that fails on truly malformed input.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.