alibaba/nacos · error · IllegalArgumentException

Agent Version storage {field} must be a string

Error message

Agent Version storage {field} must be a string

What it means

During JSON-shape validation, a text field's JSON value is not a string (for example provider given a number, boolean, object, or array). The serializer type-checks each text field before typed binding so the error message names the field.

Source

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

            throw new IllegalArgumentException("Invalid Agent Version storage " + field);
        }
    }
    
    private static void validateOptionalText(String field, String value, int maxLength) {
        if (value != null) {
            validateRequiredText(field, value, maxLength);
        }
    }
    
    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");

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Ensure provider/key/keyFormat/agentNameCodec/contentDigest/mediaType are JSON strings in the stored column
  2. Re-publish the version to regenerate a correctly typed descriptor

Example fix

// before
{"provider":1,...}
// 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 field type invalid", e);
}

Prevention

When it happens

Trigger: deserialize() of JSON like {"provider":1}, {"key":true}, {"contentDigest":{}}, or {"mediaType":[]}. A bad writer emitting the wrong JSON type triggers it.

Common situations: A hand-edited JSON with the wrong value type; a custom writer that serializes a number where a string is expected.

Related errors

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