alibaba/nacos · error · IllegalArgumentException

Agent Version storage descriptor JSON must not be empty

Error message

Agent Version storage descriptor JSON must not be empty

What it means

First guard inside deserialize()/validateJsonShape. It fires when the input string is null or empty (""), meaning the storage descriptor has no content at all. This is a fail-fast check before any JSON parsing is attempted.

Source

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

     * @param json JSON read from {@code ai_resource_version.storage}
     * @return decoded storage descriptor
     * @throws IllegalArgumentException when JSON or descriptor fields are invalid
     */
    public static AgentVersionStorageDescriptor deserialize(String json) {
        validateJsonShape(json);
        final AgentVersionStorageDescriptor descriptor;
        try {
            descriptor = JacksonUtils.toObj(json, AgentVersionStorageDescriptor.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid Agent Version storage descriptor", e);
        }
        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);
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure the Agent Version content was saved via AgentVersionStorageService.save(...) so the storage column is populated
If the row is stale or orphaned, delete it or re-publish the version
Verify AgentPersistenceService.claimVersion writes the storage column atomically with the row insert

Defensive patterns

Strategy: validation

Validate before calling

String storage = row.getStorage();
if (storage == null || storage.isEmpty()) {
    throw new NacosException(NacosException.SERVER_ERROR,
        "Agent Version has no storage descriptor: " + agentName + '@' + version);
}
AgentVersionStorageDescriptor d =
    AgentVersionStorageDescriptorSerializer.deserialize(storage);

Try / catch

try {
    AgentVersionStorageDescriptorSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    // handle missing/empty storage
}

Prevention

Reject null/empty storage before calling deserialize
Ensure AgentVersionStorageService.save always populates the storage column atomically with the version row

When it happens

Trigger: AgentVersionStorageDescriptorSerializer.deserialize(null) or deserialize(""). Reached when row.getStorage() returns null/empty, i.e. a version row with no storage descriptor (incomplete insert, draft never persisted, migration gap).

Common situations: A draft Agent Version row created before content was saved; a DB migration that left the storage column NULL; a custom persistence layer returning null; calling deserialize on an unsaved entity.

Related errors

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