alibaba/nacos · error · IllegalArgumentException

Invalid agentName: {agentName}

Error message

Invalid agentName: {agentName}

What it means

Thrown by AgentValidationUtils.validateAgentName on the first guard when agentName is null, empty, or longer than MAX_AGENT_NAME_LENGTH (64 characters). This is the length/emptiness branch; a separate branch (error 519) handles non-printable-ASCII and whitespace-only names. The Agent name is the per-namespace unique identifier of an Agent resource and must be a non-empty printable-ASCII string up to 64 chars.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentValidationUtils.java:89

     * @throws IllegalArgumentException when invalid
     */
    public static void validateNamespaceId(String namespaceId) {
        if (namespaceId == null || namespaceId.length() > MAX_NAMESPACE_LENGTH
            || !NAMESPACE_PATTERN.matcher(namespaceId).matches()) {
            throw new IllegalArgumentException("Invalid namespaceId: " + namespaceId);
        }
    }
    
    /**
     * Validate an Agent name without rewriting it.
     *
     * @param agentName Agent name
     * @throws IllegalArgumentException when invalid
     */
    public static void validateAgentName(String agentName) {
        if (agentName == null || agentName.isEmpty()
            || agentName.length() > MAX_AGENT_NAME_LENGTH) {
            throw new IllegalArgumentException("Invalid agentName: " + agentName);
        }
        boolean containsNonSpace = false;
        for (int i = 0; i < agentName.length(); i++) {
            char current = agentName.charAt(i);
            if (current < 0x20 || current > 0x7E) {
                throw new IllegalArgumentException("Invalid agentName: " + agentName);
            }
            if (current > 0x20) {
                containsNonSpace = true;
            }
        }
        if (!containsNonSpace) {
            throw new IllegalArgumentException("Invalid agentName: " + agentName);
        }
    }
    
    /**
     * Validate an Agent version.

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set agentName to a non-empty string of <= 64 printable-ASCII characters.
2. Shorten generated names (e.g. derive a slug) to stay within 64 chars.
3. Ensure the field is bound in your payload and not omitted.
4. Validate with AgentValidationUtils.validateAgentName(name) before submission.

Example fix

// before
agent.setAgentName(null); // rejected
agent.setAgentName("");    // rejected
agent.setAgentName(longGeneratedName65PlusChars); // > 64 -> rejected
// after
agent.setAgentName("order-agent");

import com.alibaba.nacos.api.ai.utils.AgentValidationUtils;
AgentValidationUtils.validateAgentName(agentName); // throws 'Invalid agentName: ...'

static boolean validAgentNameLength(String name) {
    return name != null && !name.isEmpty() && name.length() <= 64;
}

try {
    AgentValidationUtils.validateAgentName(agentName);
} catch (IllegalArgumentException e) {
    // if message matches length/null branch: shorten or supply the name, then retry
}

When it happens

Trigger: Any Agent API call or runtime snapshot push whose agentName is null, "", or > 64 characters. Reached both directly (validateAgentName) and indirectly via EndpointNaturalKey.of / validateRuntimeEndpointSnapshot.

Common situations: Forgetting to set agentName; passing an empty string from an unbound form; a generated name longer than 64 chars; concatenating components into a name that overflows the cap.

Related errors

• 20002
• 20002
• Invalid Agent Version storage {field}
• Invalid {fieldName}: {value}
• Invalid {fieldName}: exceeds {maximum}

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