alibaba/nacos · error · IllegalArgumentException

Missing Agent Version storage field

Error message

Missing Agent Version storage field: {field}

What it means

During JSON-shape validation, a required text field (provider, key, contentDigest, or mediaType) is absent from the JSON object. keyFormat and agentNameCodec are optional and may be omitted.

Solutions

  1. Include all required fields (provider, key, contentDigest, mediaType, plus schemaVersion and size) in the stored JSON
  2. Re-publish the version to regenerate a complete descriptor
  3. Restore the row from a backup if the original is lost

Example fix

// before
{"key":"...","contentDigest":"sha256:...","mediaType":"...","schemaVersion":1,"size":128}
// after (provider added)
{"provider":"nacos_config","key":"...","contentDigest":"sha256:...","mediaType":"...","schemaVersion":1,"size":128}
Defensive patterns

Strategy: try-catch

Try / catch

try {
    AgentVersionStorageDescriptorSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    throw new NacosException(NacosException.SERVER_ERROR, "Corrupt storage descriptor: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: deserialize() of a JSON object missing one of provider/key/contentDigest/mediaType. For example, deleting the "key" field from the stored descriptor.

Common situations: A hand-edited JSON with a field removed; a partial JSON document; an older descriptor format missing a now-required field.

Related errors

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

Appendix: source

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

    
    private static void validateRequiredText(String field, String value, int maxLength) {
        if (value == null || value.isEmpty() || value.length() > maxLength) {
            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)) {

View on GitHub (pinned to 9b989acdf1)