alibaba/nacos · error · IllegalArgumentException

Agent Version storage size must be between 0 and {MAX_CONTEN

Error message

Agent Version storage size must be between 0 and {MAX_CONTENT_SIZE}

What it means

The size field is null, negative, or greater than 1048576 (MAX_CONTENT_SIZE, 1 MiB). The size must be a non-negative long within the 1 MiB cap and must match the actual persisted content byte length (which is re-verified in AgentVersionStorageService.load).

Source

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

        }
        validateRequiredText("key", descriptor.getKey(), MAX_KEY_LENGTH);
        validateOptionalText("keyFormat", descriptor.getKeyFormat(), MAX_FORMAT_LENGTH);
        validateOptionalText("agentNameCodec", descriptor.getAgentNameCodec(), MAX_FORMAT_LENGTH);
        if (descriptor.getContentDigest() == null
            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {
            throw new IllegalArgumentException("Invalid Agent Version contentDigest");
        }
        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {
            throw new IllegalArgumentException("Agent Version mediaType must be "
                + AGENT_VERSION_MEDIA_TYPE);
        }
        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {
            throw new IllegalArgumentException("Agent Version storage schemaVersion must be "
                + SCHEMA_VERSION);
        }
        Long size = descriptor.getSize();
        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(
                "Agent Version storage size must be between 0 and " + MAX_CONTENT_SIZE);
        }
        if (NACOS_CONFIG_PROVIDER.equals(provider)) {
            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {
                throw new IllegalArgumentException("nacos_config keyFormat must be "
                    + NACOS_CONFIG_KEY_FORMAT);
            }
            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {
                throw new IllegalArgumentException("nacos_config agentNameCodec must be "
                    + RAD_ASCII_AGENT_NAME_CODEC);
            }
        }
    }
    
    private static void validateRequiredText(String field, String value, int maxLength) {
        if (value == null || value.isEmpty() || value.length() > maxLength) {
            throw new IllegalArgumentException("Invalid Agent Version storage " + field);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Derive size from serializedContent.getSize() returned by AgentVersionContentSerializer
Reduce the Agent Version content below 1 MiB if it is too large
Ensure size matches the persisted byte length exactly (load() cross-checks it)

Example fix

// before
descriptor.setSize(null);
// after
descriptor.setSize((long) serializedContent.getSize());

Defensive patterns

Strategy: validation

Validate before calling

long size = serializedContent.getSize();
if (size < 0 || size > AgentVersionContentSerializer.MAX_CONTENT_SIZE) {
    throw new IllegalArgumentException("content size must be 0.." + AgentVersionContentSerializer.MAX_CONTENT_SIZE);
}
descriptor.setSize(size);

Prevention

Derive size from AgentVersionContentSerializer's SerializedContent.getSize()
Enforce the 1 MiB content cap at the API boundary before serialization

When it happens

Trigger: validate()/serialize() on a descriptor whose size is null, -1, or > 1048576. Reached when content exceeds the 1 MiB limit, size is left unset, or the size no longer matches after a partial rewrite.

Common situations: Agent Version content larger than 1 MiB; size left null during construction; a rewrite that changed content length without updating size.

Related errors

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