alibaba/nacos · error · IllegalArgumentException

AgentVersionContent schemaVersion must be {AgentVersionConte

Error message

AgentVersionContent schemaVersion must be {AgentVersionContent.SCHEMA_VERSION}

What it means

Thrown by validate when content.getSchemaVersion() does not equal the constant AgentVersionContent.SCHEMA_VERSION (1). The schemaVersion guards against reading content written by an incompatible future or past storage schema.

Source

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

            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);
        }
        List<AgentCallInterface> callInterfaces = content.getCallInterfaces();
        if (callInterfaces == null || callInterfaces.isEmpty()
            || callInterfaces.size() > MAX_CALL_INTERFACES) {
            throw new IllegalArgumentException(
                "AgentVersionContent callInterfaces must contain 1 to " + MAX_CALL_INTERFACES
                    + " items");
        }
        Set<String> protocols = new HashSet<String>();
        for (AgentCallInterface callInterface : callInterfaces) {
            AgentModelValidator.validateCallInterface(callInterface);
            if (!protocols.add(callInterface.getProtocol())) {
                throw new IllegalArgumentException(
                    "Duplicate CallInterface protocol: " + callInterface.getProtocol());
            }
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use new AgentVersionContent(callInterfaces) which sets schemaVersion to SCHEMA_VERSION.
2. If upgrading the storage schema, increment SCHEMA_VERSION and provide a migration path; do not mix versions.
3. For manual construction, call content.setSchemaVersion(AgentVersionContent.SCHEMA_VERSION).

Example fix

// before
AgentVersionContent c = new AgentVersionContent();
c.setCallInterfaces(ifaces);

// after
AgentVersionContent c = new AgentVersionContent(ifaces); // sets schemaVersion=1

AgentVersionContent c = new AgentVersionContent(callInterfaces); // sets schemaVersion=1

When it happens

Trigger: Serializing/deserializing content whose schemaVersion is null or an integer other than 1. Occurs when content is built manually without schemaVersion, or when persisted bytes were written by a different schema version of the serializer.

Common situations: Manual construction with the default constructor (schemaVersion stays null), or a version skew between a writer using a newer schema and a reader expecting schemaVersion 1.

Related errors

• AgentVersionContent bytes must not be null
• AgentVersionContent must not be null
• AgentVersionContent kind must be {AgentVersionContent.KIND}
• AgentVersionContent callInterfaces must contain 1 to {MAX_CA
• Duplicate CallInterface protocol: {callInterface.getProtocol

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