alibaba/nacos · error · IllegalArgumentException

Agent Version storage descriptor must contain one JSON value

Error message

Agent Version storage descriptor must contain one JSON value

What it means

Inside validateSingleJsonValue, after skipping the first JSON value the parser finds additional tokens. This means the input contains more than one top-level JSON value, for example two concatenated objects. The serializer enforces exactly one top-level value.

Source

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

    
    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

Store exactly one JSON object in the column
Overwrite the column on update rather than appending
Re-publish the version to write a single clean descriptor

Example fix

// before (stored column)
{"provider":"nacos_config",...}{"provider":"nacos_config",...}
// after
{"provider":"nacos_config",...}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    AgentVersionStorageDescriptorSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    throw new NacosException(NacosException.SERVER_ERROR, "Storage descriptor has trailing JSON", e);
}

Prevention

Overwrite the storage column on update; never append
Ensure exactly one JSON object is stored per version row

When it happens

Trigger: AgentVersionStorageDescriptorSerializer.deserialize(validJson + "{}") or any input with trailing JSON after the first value.

Common situations: Two descriptors accidentally concatenated into one column; a writer bug that appends instead of overwriting the storage cell.

Related errors

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