alibaba/nacos · error · IllegalArgumentException

Version cannot be blank

Error message

Version cannot be blank

What it means

AgentSpecUtils.buildAgentSpecVersionGroup throws IllegalArgumentException when the version parameter is blank (null, empty, or whitespace-only). The version is embedded in the group string and must be a non-empty identifier.

Source

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

        } 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 version is non-blank before calling buildAgentSpecVersionGroup.
2. Default to a sensible version (e.g. 'v1' or 'latest') if your business logic allows it.
3. Enforce version presence at the API entry point.

Example fix

// before
String group = AgentSpecUtils.buildAgentSpecVersionGroup("myAgent", null);

// after
String version = StringUtils.isBlank(reqVersion) ? "v1" : reqVersion;
String group = AgentSpecUtils.buildAgentSpecVersionGroup("myAgent", version);

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

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

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

When it happens

Trigger: Calling buildAgentSpecVersionGroup with a null or empty version. Happens when version is derived from a default that was never set, or when the caller assumes version is optional.

Common situations: A new AgentSpec version was not assigned before calling buildAgentSpecVersionGroup. A UI form leaves the version field empty. A migration script processes records with missing version data.

Related errors

• AgentSpec name cannot be blank
• Version cannot be blank
• PARAMETER_MISSING
• Prompt key cannot be blank
• 10000

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