alibaba/nacos · error · IllegalArgumentException

AgentVersionContent must not be null

Error message

AgentVersionContent must not be null

What it means

Thrown by the private validate method when the deserialized AgentVersionContent object is null. After Jackson binding, a null result means the JSON was literally 'null' or binding produced no object; this is treated as invalid content.

Source

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

        }
        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);
        }
        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>();

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Ensure you pass a non-null AgentVersionContent to serialize.
  2. Construct content via new AgentVersionContent(callInterfaces) or the builder used by the SDK.

Example fix

// before
SerializedContent s = AgentVersionContentSerializer.serialize(null);

// after
AgentVersionContent content = new AgentVersionContent(callInterfaces);
SerializedContent s = AgentVersionContentSerializer.serialize(content);
Defensive patterns

Strategy: validation

Validate before calling

java.util.Objects.requireNonNull(content, "AgentVersionContent");
SerializedContent sc = AgentVersionContentSerializer.serialize(content);

Prevention

When it happens

Trigger: Deserializing bytes whose JSON value is null, or a binding path that yields null. validateStorageJsonShape would normally reject a literal null root earlier (root == null -> 'must be a JSON object'), so reaching here implies validate is called from serialize with a null content argument.

Common situations: Calling serialize(null) — the validate(content) at the top of serialize forwards null here. A caller forgot to construct the content object.

Related errors

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