alibaba/nacos · error · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

Required parameter `promptKey` not present

What it means

Thrown by NacosPromptCacheHolder.subscribePrompt when promptKey is blank. subscribePrompt performs the initial query synchronously, primes the cache, then polls for prompt changes keyed on the prompt key (plus version/label). An empty key cannot identify the prompt resource, so the guard rejects it as INVALID_PARAM before the proxy call.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/cache/NacosPromptCacheHolder.java:90

        return queryPrompt(promptKey, version, label, null);
    }
    
    private Prompt queryPrompt(String promptKey, String version, String label, String md5)
        throws NacosException {
        return aiClientProxy.queryPrompt(promptKey, version, label, md5);
    }
    
    /**
     * Subscribe prompt and start polling for prompt changes.
     *
     * @param promptKey prompt key
     * @return current Prompt object, null if not found
     * @throws NacosException if error occurs
     */
    public Prompt subscribePrompt(String promptKey, String version, String label)
        throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosException(NacosException.INVALID_PARAM,
                "Required parameter `promptKey` not present");
        }
        String cacheKey = CacheKeyUtils.buildPromptKey(promptKey, version, label);
        
        Prompt prompt = null;
        try {
            prompt = queryPrompt(promptKey, version, label);
            processPrompt(promptKey, cacheKey, prompt);
        } catch (NacosException e) {
            if (e.getErrCode() != NacosException.NOT_FOUND) {
                throw e;
            }
            processPrompt(promptKey, cacheKey, null);
        }
        addPromptUpdateTask(promptKey, version, label);
        LOGGER.info("Subscribed prompt: {}, version: {}, label: {}", promptKey, version, label);
        return prompt;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate promptKey is non-blank before calling subscribePrompt.
2. Make promptKey a required field wherever prompts are referenced and fail fast if missing.
3. Pass version/label as optional only after confirming the key is present.

Example fix

// before
cache.subscribePrompt(promptKey, version, label);
// after
if (StringUtils.isBlank(promptKey)) {
    throw new IllegalArgumentException("promptKey is required");
}
cache.subscribePrompt(promptKey, version, label);

if (StringUtils.isBlank(promptKey)) {
    throw new IllegalArgumentException("promptKey is required");
}
cache.subscribePrompt(promptKey, version, label);

When it happens

Trigger: Calling subscribePrompt(null, ...), subscribePrompt("", ...) or with a whitespace-only promptKey. version and label are optional but the key is mandatory.

Common situations: Prompt key read from config/ENV that was not set; key parsed from an incoming request whose promptKey field was omitted; test subscribe with an uninitialized key field.

Related errors

• INVALID_PARAM
• 10000
• 10000
• 10000
• 10000

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