alibaba/nacos · error · IllegalArgumentException

Invalid AgentVersionContent

Error message

Invalid AgentVersionContent

What it means

Thrown by AgentVersionContentSerializer.deserialize when Jackson cannot parse the bytes into an AgentVersionContent (NacosDeserializationException), after the bytes passed shape validation. The raw JSON is structurally a single value and an object, but field-level JSON decoding fails.

Source

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

     *
     * @param bytes persisted Agent Version content bytes
     * @return deserialized content
     * @throws IllegalArgumentException when bytes are invalid or out of contract
     */
    public static AgentVersionContent deserialize(byte[] bytes) {
        if (bytes == null) {
            throw new IllegalArgumentException("AgentVersionContent bytes must not be null");
        }
        if (bytes.length > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(
                "AgentVersionContent exceeds " + MAX_CONTENT_SIZE + " bytes");
        }
        validateStorageJsonShape(bytes);
        final AgentVersionContent content;
        try {
            content = JacksonUtils.toObj(bytes, AgentVersionContent.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid AgentVersionContent", e);
        }
        validate(content);
        return content;
    }
    
    private static void validate(AgentVersionContent content) {
        if (content == null) {
            throw new IllegalArgumentException("AgentVersionContent must not be null");
        }
        if (!AgentVersionContent.KIND.equals(content.getKind())) {
            throw new IllegalArgumentException("AgentVersionContent kind must be "
                + AgentVersionContent.KIND);
        }
        if (!Integer.valueOf(AgentVersionContent.SCHEMA_VERSION)
            .equals(content.getSchemaVersion())) {
            throw new IllegalArgumentException("AgentVersionContent schemaVersion must be "
                + AgentVersionContent.SCHEMA_VERSION);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the cause NacosDeserializationException for the offending field and value type.
2. Re-publish the version with a conforming AgentVersionContent built through the API/SDK.
3. If migrating schema, ensure the writer and reader agree on field types.

try {
    return AgentVersionContentSerializer.deserialize(bytes);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Invalid AgentVersionContent")
        && e.getCause() instanceof NacosDeserializationException) {
        throw corruptedContent("Agent Version content JSON binding failed", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Persisted bytes are valid JSON and a single object but contain a field whose value type cannot be bound to the AgentVersionContent model — e.g. callInterfaces is a JSON string instead of an array, or schemaVersion is a non-integer.

Common situations: Content was hand-edited or written by a non-conforming client, or a schema migration left a field with an unexpected type. The shape check (validateStorageJsonShape) permits the top-level structure but Jackson binding to typed fields fails.

Related errors

• AgentVersionContent must be a JSON object
• AgentVersionContent JSON must not be empty
• AgentVersionContent must contain one JSON value
• Unknown {objectName} field: {field}
• Unable to serialize AgentVersionContent

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