alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version storage descriptor

Error message

Invalid Agent Version storage descriptor

What it means

Thrown by deserialize() when the stored JSON passes the structural shape check (single object, only known fields) but Jackson cannot bind it onto AgentVersionStorageDescriptor. The original NacosDeserializationException is attached as the cause, so it indicates a value that cannot be coerced to the target Java type (for example a numeric field given a non-coercible string or object).

Source

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

                "Unable to serialize Agent Version storage descriptor",
                e);
        }
    }
    
    /**
     * Deserialize and validate an Agent Version storage descriptor.
     *
     * @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) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Read the cause NacosDeserializationException to find the offending field and value, then correct the stored JSON so each field matches its Java type (strings for provider/key/keyFormat/agentNameCodec/contentDigest/mediaType, integers for schemaVersion/size)
2. Re-publish the Agent Version so the server rewrites a valid descriptor via AgentVersionStorageService
3. Regenerate the descriptor through AgentVersionStorageService.prepare/save instead of hand-editing the column
4. If the row is unrecoverable, delete the corrupted version row and recreate it

Example fix

// before (stored column)
{"provider":"nacos_config","key":"...","schemaVersion":"1.0","size":128}
// after
{"provider":"nacos_config","key":"...","schemaVersion":1,"size":128}

try {
    AgentVersionStorageDescriptor d =
        AgentVersionStorageDescriptorSerializer.deserialize(row.getStorage());
} catch (IllegalArgumentException e) {
    throw new NacosException(NacosException.SERVER_ERROR,
        "Stored Agent Version descriptor is invalid: " + agentName + '@' + version, e);
}

When it happens

Trigger: Calling AgentVersionStorageDescriptorSerializer.deserialize(row.getStorage()) on a row whose JSON has a field whose value Jackson refuses to map (e.g. schemaVersion:"1.0", size:{}). Reached via AgentPersistenceService.requireStorageDescriptor:1443, toVersionSummary:1371, sameVersion:1474, and AgentDiscoveryApplicationService:313.

Common situations: Manually editing the ai_resource_version.storage column; a tooling/migration step that wrote a numeric field as a string; an older Nacos writer that emitted a slightly different value type for a field.

Related errors

• Agent Version storage descriptor must be a JSON object
• Unknown Agent Version storage descriptor field: {fieldName}
• Missing Agent Version storage field: {field}
• Agent Version storage {field} must be a string
• Agent Version storage {field} must be an integer

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