alibaba/nacos · error · IllegalArgumentException

AgentVersionContent must be a JSON object

Error message

AgentVersionContent must be a JSON object

What it means

Thrown by validateStorageJsonShape when the parsed JSON root is null (i.e. the JSON literal 'null'). The storage projection must be a JSON object, not a null value.

Source

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

        char[] encoded = new char[digest.length * 2];
        for (int i = 0; i < digest.length; i++) {
            int value = digest[i] & 0xFF;
            encoded[i * 2] = HEX[value >>> 4];
            encoded[i * 2 + 1] = HEX[value & 0x0F];
        }
        return new String(encoded);
    }
    
    private static void validateStorageJsonShape(byte[] bytes) {
        validateSingleJsonValue(bytes);
        final Map<?, ?> root;
        try {
            root = JacksonUtils.toObj(bytes, Map.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid AgentVersionContent", e);
        }
        if (root == null) {
            throw new IllegalArgumentException("AgentVersionContent must be a JSON object");
        }
        rejectUnknownFields(root, CONTENT_FIELDS, "AgentVersionContent");
        Object callInterfaces = root.get("callInterfaces");
        if (!(callInterfaces instanceof List)) {
            return;
        }
        for (Object callInterface : (List<?>) callInterfaces) {
            if (!(callInterface instanceof Map)) {
                continue;
            }
            Map<?, ?> interfaceObject = (Map<?, ?>) callInterface;
            rejectUnknownFields(interfaceObject, CALL_INTERFACE_FIELDS, "AgentCallInterface");
            Object endpoints = interfaceObject.get("declaredEndpoints");
            if (!(endpoints instanceof List)) {
                continue;
            }
            for (Object endpoint : (List<?>) endpoints) {
                if (endpoint instanceof Map) {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Re-publish the version; content should never be persisted as JSON null.
  2. Audit the write path that produced the 'null' bytes — it likely serialized a null AgentVersionContent.
Defensive patterns

Strategy: try-catch

Try / catch

try {
    return AgentVersionContentSerializer.deserialize(bytes);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must be a JSON object")) {
        throw corruptedContent("stored content is JSON null", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Deserializing bytes whose content is the JSON token sequence representing null. validateSingleJsonValue passes (one value) but Map binding yields null, which is rejected here.

Common situations: A storage cell contains the literal string 'null', or a writer erroneously serialized a null reference. Indicates a logic error in the write path.

Related errors

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