alibaba/nacos · error · IllegalArgumentException

Agent Version storage descriptor must be a JSON object

Error message

Agent Version storage descriptor must be a JSON object

What it means

After parsing the input as a Map, the root is null. This happens specifically for the JSON literal `null` (the four characters n-u-l-l), which is a single valid JSON value but not an object. The serializer requires a JSON object.

Source

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

        }
        validate(descriptor);
        return descriptor;
    }
    
    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");
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Replace the literal 'null' text with a proper descriptor JSON object
Re-publish the Agent Version so the server writes a valid descriptor
Audit the write path that produced the literal null string (look for String.valueOf or careless null serialization)

Example fix

// before (stored column literally contains)
null
// after
{"provider":"nacos_config","key":"namespace:agent-version:agent__Agent__1.0.0.json",...}

Defensive patterns

Strategy: try-catch

Validate before calling

if (json != null && "null".equals(json.trim())) {
    throw new NacosException(NacosException.SERVER_ERROR,
        "Agent Version storage descriptor is the literal 'null'");
}

Try / catch

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

Prevention

Never store String.valueOf(null) or a JSON null token in the storage column
Audit write paths for careless null serialization

When it happens

Trigger: AgentVersionStorageDescriptorSerializer.deserialize("null"). The storage column literally contains the text `null`.

Common situations: A write path that stored String.valueOf(null) or a JSON null token instead of omitting the field; an ORM mapping bug; a bad manual edit that typed the word null into the column.

Related errors

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