{"record":{"id":"09f5fd1bccddd21c","repo":"alibaba/nacos","slug":"invalid-agentname-agentname","errorCode":null,"errorMessage":"Invalid agentName: {agentName}","messagePattern":"Invalid agentName: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentValidationUtils.java","lineNumber":89,"sourceCode":"     * @throws IllegalArgumentException when invalid\n     */\n    public static void validateNamespaceId(String namespaceId) {\n        if (namespaceId == null || namespaceId.length() > MAX_NAMESPACE_LENGTH\n            || !NAMESPACE_PATTERN.matcher(namespaceId).matches()) {\n            throw new IllegalArgumentException(\"Invalid namespaceId: \" + namespaceId);\n        }\n    }\n    \n    /**\n     * Validate an Agent name without rewriting it.\n     *\n     * @param agentName Agent name\n     * @throws IllegalArgumentException when invalid\n     */\n    public static void validateAgentName(String agentName) {\n        if (agentName == null || agentName.isEmpty()\n            || agentName.length() > MAX_AGENT_NAME_LENGTH) {\n            throw new IllegalArgumentException(\"Invalid agentName: \" + agentName);\n        }\n        boolean containsNonSpace = false;\n        for (int i = 0; i < agentName.length(); i++) {\n            char current = agentName.charAt(i);\n            if (current < 0x20 || current > 0x7E) {\n                throw new IllegalArgumentException(\"Invalid agentName: \" + agentName);\n            }\n            if (current > 0x20) {\n                containsNonSpace = true;\n            }\n        }\n        if (!containsNonSpace) {\n            throw new IllegalArgumentException(\"Invalid agentName: \" + agentName);\n        }\n    }\n    \n    /**\n     * Validate an Agent version.","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentValidationUtils.java#L71-L107","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set agentName to a non-empty string of <= 64 printable-ASCII characters.","Shorten generated names (e.g. derive a slug) to stay within 64 chars.","Ensure the field is bound in your payload and not omitted.","Validate with AgentValidationUtils.validateAgentName(name) before submission."],"exampleFix":"// before\nagent.setAgentName(null); // rejected\nagent.setAgentName(\"\");    // rejected\nagent.setAgentName(longGeneratedName65PlusChars); // > 64 -> rejected\n// after\nagent.setAgentName(\"order-agent\");","handlingStrategy":"validation","validationCode":"import com.alibaba.nacos.api.ai.utils.AgentValidationUtils;\nAgentValidationUtils.validateAgentName(agentName); // throws 'Invalid agentName: ...'","typeGuard":"static boolean validAgentNameLength(String name) {\n    return name != null && !name.isEmpty() && name.length() <= 64;\n}","tryCatchPattern":"try {\n    AgentValidationUtils.validateAgentName(agentName);\n} catch (IllegalArgumentException e) {\n    // if message matches length/null branch: shorten or supply the name, then retry\n}","preventionTips":["agentName: non-empty, <= 64 chars (length branch).","Keep generated names short; derive a slug for long display names.","Bind the field explicitly in payloads rather than relying on defaults."],"tags":["ai-agent","validation","agent-name","length-limit","required-field"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}