alibaba/nacos · error · IllegalArgumentException

Missing Agent Version storage field: {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.

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)

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}

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

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

• Unknown Agent Version storage descriptor field: {fieldName}
• Agent Version storage descriptor must be a JSON object
• Agent Version storage {field} must be a string
• Agent Version storage {field} must be an integer
• Agent Version storage descriptor must contain one JSON value

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