alibaba/nacos · error · IllegalArgumentException

Unknown {objectName} field: {field}

Error message

Unknown {objectName} field: {field}

What it means

Thrown by rejectUnknownFields when a JSON object contains a field not in the allowed set for its level. The storage projection has a closed schema: AgentVersionContent allows {kind, schemaVersion, callInterfaces}; AgentCallInterface allows {protocol, protocolVersion, descriptorMediaType, nativeDescriptor, endpointSourceOrder, declaredEndpoints}; DeclaredEndpoint allows {uri, transport, priority, weight, metadata}.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java:290

        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(bytes)) {
            if (parser.nextToken() == null) {
                throw new IllegalArgumentException("AgentVersionContent JSON must not be empty");
            }
            parser.skipChildren();
            if (parser.nextToken() != null) {
                throw new IllegalArgumentException(
                    "AgentVersionContent must contain one JSON value");
            }
        } catch (IOException e) {
            throw new IllegalArgumentException("Invalid AgentVersionContent", e);
        }
    }
    
    private static void rejectUnknownFields(Map<?, ?> value, Set<String> fields,
        String objectName) {
        for (Object field : value.keySet()) {
            if (!fields.contains(field)) {
                throw new IllegalArgumentException("Unknown " + objectName + " field: " + field);
            }
        }
    }
    
    /**
     * Immutable persisted bytes, digest and byte count for one Agent Version content object.
     */
    public static final class SerializedContent {
        
        private final byte[] bytes;
        
        private final String contentDigest;
        
        private SerializedContent(byte[] bytes, String contentDigest) {
            this.bytes = bytes;
            this.contentDigest = contentDigest;
        }
        

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Remove the offending field named in the message from the persisted JSON.
2. Re-serialize through AgentVersionContentSerializer.serialize which only emits allowed fields.
3. If the field is legitimately needed, add it to the corresponding FIELDS set and update the spec.

// allowed top-level fields
Set<String> allowed = Set.of("kind", "schemaVersion", "callInterfaces");
for (String f : yourFields) {
    if (!allowed.contains(f)) {
        throw new IllegalArgumentException("disallowed field: " + f);
    }
}

try {
    return AgentVersionContentSerializer.deserialize(bytes);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown ")) {
        log.warn("rejecting content with unknown field: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Deserializing content whose JSON includes an extra field at any level — e.g. a top-level 'version' field, a callInterface with 'description', or an endpoint with 'region'. The shape check walks the JSON before typed binding and rejects the unknown field by name.

Common situations: A client or older serializer wrote content with fields no longer (or never) in the storage schema, or a hand-crafted JSON blob includes extra metadata at the wrong nesting level.

Related errors

• Invalid AgentVersionContent
• AgentVersionContent kind must be {AgentVersionContent.KIND}
• AgentVersionContent must be a JSON object
• AgentVersionContent JSON must not be empty
• AgentVersionContent must contain one JSON value

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