alibaba/nacos · error · NacosDeserializationException

101

101

Error message

Nacos deserialize for class [%s] failed, cause error[%s]. 

What it means

Thrown by Jackson3JsonAdapterDelegate.read(JsonReader, Class) when Jackson 3 fails to deserialize JSON into the target class. Wrapped as NacosDeserializationException (code 101) naming the class and the cause error. The Jackson 3 counterpart of error 744, catching JacksonException instead of broad Exception.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/json/Jackson3JsonAdapterDelegate.java:149

    
    private JavaType constructJavaType(Type type) {
        return mapper.constructType(type);
    }
    
    private <T> T write(Object obj, JsonWriter<T> writer) {
        try {
            return writer.write();
        } catch (JacksonException e) {
            Class<?> serializedClass = obj == null ? Object.class : obj.getClass();
            throw new NacosSerializationException(serializedClass, e);
        }
    }
    
    private <T> T read(JsonReader<T> reader, Class<?> cls) {
        try {
            return reader.read();
        } catch (JacksonException e) {
            throw new NacosDeserializationException(cls, e);
        }
    }
    
    private <T> T read(JsonReader<T> reader, Type type) {
        try {
            return reader.read();
        } catch (JacksonException e) {
            throw new NacosDeserializationException(type, e);
        }
    }
    
    private static ObjectMapper createObjectMapper(Collection<NacosJsonSubtype> subtypes) {
        JsonMapper.Builder builder = JsonMapper.builderWithJackson2Defaults();
        builder.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        builder.changeDefaultPropertyInclusion(new NonNullPropertyInclusion());
        registerSubtypes(builder, subtypes);
        return builder.build();
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect e.getCause() (a Jackson 3 JacksonException subtype) for the exact path and reason.
2. Add/fix a @JsonCreator constructor or default constructor on the target class.
3. Log and compare the raw payload against the class to find the offending field.
4. For polymorphic types, supply @JsonTypeInfo/@JsonSubTypes or register a NacosJsonSubtype on the delegate.
5. If the payload is an error body, branch on HTTP status before deserializing to the success type.

Example fix

// before
Result r = jsonAdapter.fromJson(body, Result.class); // code 101 under Jackson 3

// after
try {
    return jsonAdapter.fromJson(body, Result.class);
} catch (NacosDeserializationException e) {
    log.error("Jackson3 failed on Result: cause={}", e.getCause().getMessage());
    throw e;
}

if (StringUtils.isBlank(json)) {
    throw new IllegalArgumentException("empty JSON for " + targetClass.getName());
}

try {
    return jsonAdapter.fromJson(json, targetClass);
} catch (NacosDeserializationException e) {
    log.error("Jackson3 deserialize {} failed: {}", targetClass.getName(),
        e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    throw e;
}

When it happens

Trigger: Using the JACKSON3 adapter and calling fromJson(json, MyClass.class) on a payload that mismatches MyClass: wrong token types, missing creator, unrecognized polymorphic type, or JSON that is an error page rather than the expected DTO.

Common situations: Migrated to Jackson 3 which is stricter about constructors and coercion; server error envelope deserialized as a success DTO; field renamed across API versions; abstract target without @JsonTypeInfo under Jackson 3.

Related errors

• 101
• 100
• AgentVersionContent must be a JSON object
• AgentVersionContent JSON must not be empty
• AgentVersionContent must contain one JSON value

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/5d85ce0744733b33. Report an issue: GitHub.