alibaba/nacos · error · IllegalArgumentException

Agent Version storage {field} must be an integer

Error message

Agent Version storage {field} must be an integer

What it means

During JSON-shape validation, schemaVersion or size is not an integer JSON token. Only Byte/Short/Integer/Long values are accepted; JSON floats (1.0, 128.5) and strings/booleans are rejected, even if they look numeric.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java:222

    
    private static void validateJsonText(Map<?, ?> root, String field, boolean optional) {
        if (!root.containsKey(field)) {
            if (optional) {
                return;
            }
            throw new IllegalArgumentException("Missing Agent Version storage field: " + field);
        }
        if (!(root.get(field) instanceof String)) {
            throw new IllegalArgumentException(
                "Agent Version storage " + field + " must be a string");
        }
    }
    
    private static void validateJsonInteger(Map<?, ?> root, String field) {
        Object value = root.get(field);
        if (!(value instanceof Byte || value instanceof Short || value instanceof Integer
            || value instanceof Long)) {
            throw new IllegalArgumentException(
                "Agent Version storage " + field + " must be an integer");
        }
    }
    
    private static void validateSingleJsonValue(String json) {
        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(json)) {
            if (parser.nextToken() == null) {
                throw new IllegalArgumentException(
                    "Agent Version storage descriptor JSON must not be empty");
            }
            parser.skipChildren();
            if (parser.nextToken() != null) {
                throw new IllegalArgumentException(
                    "Agent Version storage descriptor must contain one JSON value");
            }
        } catch (IOException e) {
            throw new IllegalArgumentException("Invalid Agent Version storage descriptor", e);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Write schemaVersion and size as JSON integers (no decimal point, no quotes)
  2. Re-publish the version to regenerate a correctly typed descriptor

Example fix

// before
{"schemaVersion":1.0,"size":"128"}
// after
{"schemaVersion":1,"size":128}
Defensive patterns

Strategy: try-catch

Try / catch

try {
    AgentVersionStorageDescriptorSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    throw new NacosException(NacosException.SERVER_ERROR, "schemaVersion/size must be JSON integers", e);
}

Prevention

When it happens

Trigger: deserialize() of JSON like {"schemaVersion":1.0}, {"size":"large"}, or {"size":128.5}.

Common situations: JSON written with a float where an integer is expected; a string-encoded size; a writer that emits numbers as strings.

Related errors

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