alibaba/nacos · error · IllegalArgumentException

{} must be an integer

Error message

{} must be an integer

What it means

The root 'schemaVersion' field in ai_resource.ext JSON must be an integer. The validateJsonInteger helper (line 388) throws this when schemaVersion is present but is not an integer type — it rejects floats, strings, booleans, and objects. Only Byte, Short, Integer, and Long are accepted (Jackson deserializes small numbers as Integer).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:389

    }
    
    private static void validateRequiredJsonText(Map<?, ?> object, String field) {
        if (!(object.get(field) instanceof String)) {
            throw new IllegalArgumentException(field + " must be a string");
        }
    }
    
    private static void validateOptionalJsonText(Map<?, ?> object, String field) {
        if (object.containsKey(field) && !(object.get(field) instanceof String)) {
            throw new IllegalArgumentException(field + " must be a string");
        }
    }
    
    private static void validateJsonInteger(Map<?, ?> object, String field) {
        Object value = object.get(field);
        if (!(value instanceof Byte || value instanceof Short || value instanceof Integer
            || value instanceof Long)) {
            throw new IllegalArgumentException(field + " must be an integer");
        }
    }
    
    private static void rejectUnknownFields(Map<?, ?> object, Set<String> allowedFields,
        String objectName) {
        for (Object field : object.keySet()) {
            if (!allowedFields.contains(field)) {
                throw new IllegalArgumentException(
                    "Unknown " + objectName + " field: " + field);
            }
        }
    }
    
    private static void validateSingleJsonValue(String json) {
        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(json)) {
            if (parser.nextToken() == null) {
                throw new IllegalArgumentException("AgentResourceExt JSON must not be empty");
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure schemaVersion is an unquoted JSON integer, e.g. 1 not 1.0 or "1".
2. The current expected value is AgentResourceExt.SCHEMA_VERSION (currently 1).
3. Audit the producer's number serialization to use integer types for this field.

Example fix

// before
{"schemaVersion":1.0}
// after
{"schemaVersion":1}

Object sv = root.get("schemaVersion");
if (!(sv instanceof Integer) && !(sv instanceof Long) && !(sv instanceof Short) && !(sv instanceof Byte)) {
    throw new IllegalArgumentException("schemaVersion must be an integer");
}

public static boolean isJsonInteger(Object value) {
    return value instanceof Byte || value instanceof Short
        || value instanceof Integer || value instanceof Long;
}

try {
    AgentResourceExtSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("schemaVersion") && e.getMessage().contains("integer")) {
        // cast or regenerate the schemaVersion as an integer
    }
    throw e;
}

When it happens

Trigger: Deserializing ai_resource.ext where 'schemaVersion' is a float (1.0), a string ("1"), or omitted entirely (which would fail the earlier unknown-field or required check).

Common situations: JSON producers that always serialize numbers as floats; hand-editing and quoting the version number; schema generators that emit schemaVersion as a string.

Related errors

• Missing AgentResourceExt field: versionCatalog
• AgentVersionCatalog onlineVersions must be an array
• {} must be an array
• {} must contain only strings
• {} must be a JSON object

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