alibaba/nacos · error · IllegalArgumentException

Unknown Agent Version storage descriptor field: {fieldName}

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.

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)

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.