alibaba/nacos · error · IllegalArgumentException

Version cannot be blank

Error message

Version cannot be blank

What it means

PromptUtils.buildPromptVersionGroup 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 value.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/prompt/PromptUtils.java:60

    private static final String DOUBLE_UNDERSCORE = "__";
    
    private PromptUtils() {
    }
    
    /**
     * Build the Nacos Config group for a specific prompt version.
     *
     * @param promptKey prompt key (name)
     * @param version   version string, e.g. "1.0.0"
     * @return config group string, e.g. "prompt__{enc_promptKey}__{enc_version}"
     * @throws IllegalArgumentException if promptKey or version is blank
     */
    public static String buildPromptVersionGroup(String promptKey, String version) {
        if (StringUtils.isBlank(promptKey)) {
            throw new IllegalArgumentException("Prompt key cannot be blank");
        }
        if (StringUtils.isBlank(version)) {
            throw new IllegalArgumentException("Version cannot be blank");
        }
        return PROMPT_GROUP_PREFIX + NacosAiConfigKeyCodec.encodeVersionedGroupSegment(promptKey)
            + DOUBLE_UNDERSCORE + NacosAiConfigKeyCodec.encodeVersionedGroupSegment(version);
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a concrete version string (e.g. '1.0.0') or resolve 'latest' before calling.
2. Validate version is non-blank at the API boundary.
3. If the business case allows, default to a known version when none is specified.

Example fix

// before
String group = PromptUtils.buildPromptVersionGroup("myPrompt", null);

// after
String version = StringUtils.isBlank(reqVersion) ? "1.0.0" : reqVersion;
String group = PromptUtils.buildPromptVersionGroup("myPrompt", 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 = PromptUtils.buildPromptVersionGroup(promptKey, version);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Version cannot be blank")) {
        return badRequest("version is required");
    }
    throw e;
}

When it happens

Trigger: Calling buildPromptVersionGroup with a null or empty version string. Happens when version is derived from a default that was not initialized, or when the caller treats version as optional.

Common situations: A prompt version was never assigned before lookup. A form submission omits the version. A default value like null is passed because no specific version was requested.

Related errors

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

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