alibaba/nacos · error · IllegalArgumentException

AgentSpec name cannot be blank

Error message

AgentSpec name cannot be blank

What it means

AgentSpecUtils.buildAgentSpecVersionGroup throws IllegalArgumentException when agentSpecName is blank (null, empty, or whitespace-only). The method constructs a Nacos Config group string and cannot produce a valid group from an empty name.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/agentspecs/AgentSpecUtils.java:103

        if (type != null && !type.trim().isEmpty()) {
            String safeType = type.trim().replace("/", ".");
            return safeType + "_" + processedName;
        } else {
            return processedName;
        }
    }
    
    /**
     * Build the Nacos Config group for a specific AgentSpec version.
     *
     * @param agentSpecName name of AgentSpec
     * @param version       version string, e.g. "v1"
     * @return config group string, e.g. "agentspec__myworker__v1"
     * @throws IllegalArgumentException if agentSpecName or version is blank
     */
    public static String buildAgentSpecVersionGroup(String agentSpecName, String version) {
        if (StringUtils.isBlank(agentSpecName)) {
            throw new IllegalArgumentException("AgentSpec name cannot be blank");
        }
        if (StringUtils.isBlank(version)) {
            throw new IllegalArgumentException("Version cannot be blank");
        }
        return AGENTSPEC_GROUP_PREFIX
            + NacosAiConfigKeyCodec.encodeVersionedGroupSegment(agentSpecName)
            + DOUBLE_UNDERSCORE + NacosAiConfigKeyCodec.encodeVersionedGroupSegment(version);
    }
    
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate agentSpecName is non-blank before calling buildAgentSpecVersionGroup.
2. Use StringUtils.isBlank() pre-check and return early or throw a domain-specific error.
3. Ensure the caller (controller, service layer) enforces non-blank name at the trust boundary.

Example fix

// before
String group = AgentSpecUtils.buildAgentSpecVersionGroup("", "v1"); // throws

// after
if (StringUtils.isBlank(agentSpecName)) {
    throw new IllegalArgumentException("agentSpecName required");
}
String group = AgentSpecUtils.buildAgentSpecVersionGroup(agentSpecName, "v1");

if (StringUtils.isBlank(agentSpecName)) {
    throw new IllegalArgumentException("agentSpecName is required");
}

public static boolean isAgentSpecNameValid(String name) {
    return name != null && !name.trim().isEmpty();
}

try {
    group = AgentSpecUtils.buildAgentSpecVersionGroup(name, version);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("AgentSpec name cannot be blank")) {
        return badRequest("agentSpecName is required");
    }
    throw e;
}

When it happens

Trigger: Calling buildAgentSpecVersionGroup with a null, empty, or whitespace-only agentSpecName parameter. Happens when the name comes from user input that was not validated, or from a deserialized object with a missing name field.

Common situations: API endpoint receives a request without the agentSpecName field. A configuration file references an AgentSpec by empty name. A loop or stream operation passes a null name from a map lookup.

Related errors

• Version cannot be blank
• Prompt key cannot be blank
• Version cannot be blank
• 10000
• 20002

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