alibaba/nacos · error · IllegalArgumentException

Unknown Agent Version storage descriptor field

Error message

Unknown Agent Version storage descriptor field: {fieldName}

What it means

The parsed JSON object contains a key that is not in the allowed FIELDS set {provider, key, keyFormat, agentNameCodec, contentDigest, mediaType, schemaVersion, size}. The serializer uses a strict allow-list to reject typos and unexpected keys, keeping the storage schema stable and forward-compatible.

Solutions

  1. Remove the unknown field from the stored JSON so it contains only the eight schema fields
  2. Upgrade all servers in the cluster to a Nacos version that recognizes the field
  3. Re-publish the version so the current-schema writer regenerates the descriptor

Example fix

// before
{"provider":"nacos_config",...,"extra":true}
// after
{"provider":"nacos_config",...}
Defensive patterns

Strategy: try-catch

Try / catch

try {
    AgentVersionStorageDescriptorSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    // log the offending field name from the message, then surface a controlled error
    throw new NacosException(NacosException.SERVER_ERROR, "Unknown field in storage descriptor", e);
}

Prevention

When it happens

Trigger: deserialize() of a descriptor JSON with an extra field, e.g. {"...","extra":true}, or a typo such as "provide":"nacos_config". Also triggered by a newer server writing a field an older server does not recognize.

Common situations: Mixed Nacos versions in a cluster where a newer writer adds a field; a manual edit adding a non-schema field; a custom storage-provider integration writing extra metadata into the descriptor.

Related errors

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

Appendix: source

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

    private static void validateJsonShape(String json) {
        if (json == null || json.isEmpty()) {
            throw new IllegalArgumentException(
                "Agent Version storage descriptor JSON must not be empty");
        }
        validateSingleJsonValue(json);
        final Map<?, ?> root;
        try {
            root = JacksonUtils.toObj(json, Map.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid Agent Version storage descriptor", e);
        }
        if (root == null) {
            throw new IllegalArgumentException(
                "Agent Version storage descriptor must be a JSON object");
        }
        for (Object fieldName : root.keySet()) {
            if (!FIELDS.contains(fieldName)) {
                throw new IllegalArgumentException(
                    "Unknown Agent Version storage descriptor field: " + fieldName);
            }
        }
        validateJsonText(root, "provider", false);
        validateJsonText(root, "key", false);
        validateJsonText(root, "keyFormat", true);
        validateJsonText(root, "agentNameCodec", true);
        validateJsonText(root, "contentDigest", false);
        validateJsonText(root, "mediaType", false);
        validateJsonInteger(root, "schemaVersion");
        validateJsonInteger(root, "size");
    }
    
    /**
     * Validate an Agent Version storage descriptor against the internal storage schema.
     *
     * @param descriptor storage descriptor
     * @throws IllegalArgumentException when the descriptor is invalid

View on GitHub (pinned to 9b989acdf1)