alibaba/nacos · error · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

parameters `promptKey` can't be empty or null

What it means

Thrown by getPromptByLabel(String, String) when promptKey is blank. The key is validated first; if non-blank, the label is then checked. This method requires BOTH a key and a non-blank label (unlike getPromptByVersion which tolerates a blank version).

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/NacosAiService.java:602

        return getPromptByVersion(promptKey, null);
    }
    
    @Override
    public Prompt getPromptByVersion(String promptKey, String version) throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `promptKey` can't be empty or null");
        }
        if (StringUtils.isBlank(version)) {
            return aiClientProxy.queryPrompt(promptKey, null, null, null);
        }
        return aiClientProxy.queryPrompt(promptKey, version, null, null);
    }
    
    @Override
    public Prompt getPromptByLabel(String promptKey, String label) throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `promptKey` can't be empty or null");
        }
        if (StringUtils.isBlank(label)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `label` can't be empty or null");
        }
        return aiClientProxy.queryPrompt(promptKey, null, label, null);
    }
    
    @Override
    public Prompt subscribePrompt(String promptKey, String version, String label,
        AbstractNacosPromptListener promptListener) throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `promptKey` can't be empty or null");
        }
        if (null == promptListener) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Pass a non-blank promptKey as the first argument (verify you have not swapped key and label).
  2. Validate both key and label at the call site, since this method requires both.
  3. If the label is optional for your flow, use getPrompt(key) or getPromptByVersion instead.

Example fix

// before
Prompt p = aiService.getPromptByLabel(label, key); // swapped args -> key blank -> throws

// after
Prompt p = aiService.getPromptByLabel(key, label); // correct order
Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(promptKey)) {
    throw new IllegalArgumentException("promptKey required");
}
Prompt p = aiService.getPromptByLabel(promptKey, label);

Type guard

static boolean canGetByLabel(String key, String label) {
    return StringUtils.isNotBlank(key) && StringUtils.isNotBlank(label);
}

Prevention

When it happens

Trigger: Calling aiService.getPromptByLabel("", "stable") or getPromptByLabel(null, label). The label is not yet validated when this fires.

Common situations: Label-driven lookup where the key comes from one config source and the label from another, and the key source is empty; mixing up argument order and passing the label first.

Related errors

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