alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version storage {field}

Error message

Invalid Agent Version storage {field}

What it means

Thrown by validateRequiredText (also reached via validateOptionalText for keyFormat/agentNameCodec when they are non-null): the field value is null, empty, or exceeds its maximum length. Applies to key (max 1024), and to keyFormat/agentNameCodec (max 64) when present.

Source

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

        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);
        }
    }
    
    private static void validateOptionalText(String field, String value, int maxLength) {
        if (value != null) {
            validateRequiredText(field, value, maxLength);
        }
    }
    
    private static void validateJsonText(Map<?, ?> root, String field, boolean optional) {
        if (!root.containsKey(field)) {
            if (optional) {
                return;
            }
            throw new IllegalArgumentException("Missing Agent Version storage field: " + field);
        }
        if (!(root.get(field) instanceof String)) {
            throw new IllegalArgumentException(

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a non-empty key within 1024 characters
2. For optional keyFormat/agentNameCodec, leave them null rather than setting an empty string
3. Shorten the agent name or version if the storage key overflows the 1024-char limit

Example fix

// before
descriptor.setKey("");
// after
descriptor.setKey("namespace:agent-version:agent__Agent__1.0.0.json");

private static void requireText(String name, String value, int max) {
    if (value == null || value.isEmpty() || value.length() > max) {
        throw new IllegalArgumentException(name + " must be non-empty and <= " + max);
    }
}
requireText("key", descriptor.getKey(), 1024);

When it happens

Trigger: validate()/serialize() on a descriptor where key is null/empty/over 1024 chars, or keyFormat/agentNameCodec is a non-null empty string or over 64 chars.

Common situations: A very deep namespace/agent/version producing a key over 1024 chars; an optional field explicitly set to "" instead of null; a truncation bug producing empty strings.

Related errors

• Agent Version storage descriptor JSON must not be empty
• Agent Version storage descriptor must be a JSON object
• Unknown Agent Version storage descriptor field: {fieldName}
• Agent Version storage descriptor must not be null
• Invalid Agent Version storage provider

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