alibaba/nacos · error · NacosDeserializationException

101

101

Error message

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

What it means

Thrown by Jackson2JsonAdapter.read(JsonReader, Class) when Jackson fails to deserialize JSON into the target class. Wrapped as NacosDeserializationException (error code 101), the message names the target class and the cause error. The catch is broad (catch Exception), so any mapper failure — mismatched JSON, unknown type, IO error — surfaces here.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/json/Jackson2JsonAdapter.java:138

    
    private JavaType constructJavaType(Type type) {
        return mapper.constructType(type);
    }
    
    private <T> T write(Object obj, JsonWriter<T> writer) {
        try {
            return writer.write();
        } catch (JsonProcessingException 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 (Exception e) {
            throw new NacosDeserializationException(cls, e);
        }
    }
    
    private <T> T read(JsonReader<T> reader, Type type) {
        try {
            return reader.read();
        } catch (Exception e) {
            throw new NacosDeserializationException(type, e);
        }
    }
    
    private static ObjectMapper createObjectMapper() {
        ObjectMapper objectMapper = new ObjectMapper();
        objectMapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        objectMapper.setSerializationInclusion(Include.NON_NULL);
        return objectMapper;
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Read NacosDeserializationException.getCause() to get the exact JsonMappingException / MismatchedInputException and the failing field.
2. Verify the raw payload matches the target class (log it before deserializing in a repro).
3. Add a public no-argument constructor and accessible setters/fields to the target class.
4. Make the target tolerant (the mapper already disables FAIL_ON_UNKNOWN_PROPERTIES, so unknown fields are fine — look for type mismatches or missing constructors instead).
5. For polymorphic targets, add @JsonTypeInfo/@JsonSubTypes or a registered NacosJsonSubtype.

Example fix

// before
Result r = jsonAdapter.fromJson(body, Result.class); // throws code 101 on bad body

// after
try {
    Result r = jsonAdapter.fromJson(body, Result.class);
} catch (NacosDeserializationException e) {
    log.error("Bad payload for Result: {}", body, e.getCause());
    throw e;
}

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

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

When it happens

Trigger: Calling a Nacos JSON deserialize-by-class path (Jackson2JsonAdapter.fromJson(json, MyClass.class)) when the payload does not match MyClass: missing required fields, wrong types, trailing data, or a class with no default constructor.

Common situations: Server returned an error envelope or HTML page where a typed DTO was expected; API version skew where a field was renamed; the target class is missing a public no-arg constructor or setters; polymorphic type info absent for an abstract target.

Related errors

• 100
• 101
• 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/40e90423028f6e26. Report an issue: GitHub.