alibaba/nacos · error · IllegalArgumentException

Prompt key cannot be blank

Error message

Prompt key cannot be blank

What it means

PromptUtils.buildPromptVersionGroup throws IllegalArgumentException when promptKey is blank (null, empty, or whitespace-only). The method builds a Nacos Config group string of the form 'prompt__{enc_key}__{enc_version}' and cannot proceed without a valid key.

Source

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

     */
    public static final String PROMPT_MAIN_DATA_ID = "content.json";
    
    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. Validate promptKey is non-blank before calling buildPromptVersionGroup.
2. Add an early-return or domain error at the controller/service layer for blank keys.
3. Use StringUtils.hasText() or StringUtils.isBlank() as a guard.

Example fix

// before
String group = PromptUtils.buildPromptVersionGroup("", "1.0.0"); // throws

// after
if (!StringUtils.hasText(promptKey)) {
    throw new IllegalArgumentException("promptKey is required");
}
String group = PromptUtils.buildPromptVersionGroup(promptKey, "1.0.0");

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

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

try {
    group = PromptUtils.buildPromptVersionGroup(promptKey, version);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Prompt key cannot be blank")) {
        return badRequest("promptKey is required");
    }
    throw e;
}

When it happens

Trigger: Calling buildPromptVersionGroup with a null or empty promptKey. Happens when the key comes from unvalidated user input, a missing JSON field, or a null map entry.

Common situations: API request omits the promptKey field. A batch job processes prompt records and encounters one with a missing key. A variable was declared but never assigned before being passed.

Related errors

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

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