alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter `promptKey` not present

What it means

Thrown by PromptClientOperationServiceImpl.queryPrompt (the runtime/client read path used by SDK long-polling) when promptKey is blank. promptKey is the mandatory identifier for a prompt; without it the query cannot be routed. Reported as PARAMETER_MISSING (HTTP 400).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/prompt/PromptClientOperationServiceImpl.java:50

 * Adds MD5-based conditional fetch for SDK client long-polling.</p>
 *
 * @author nacos
 */
@Service
public class PromptClientOperationServiceImpl implements PromptClientOperationService {
    
    private final PromptOperationService promptOperationService;
    
    public PromptClientOperationServiceImpl(@Lazy PromptOperationService promptOperationService) {
        this.promptOperationService = promptOperationService;
    }
    
    @Override
    public PromptVersionInfo queryPrompt(String namespaceId, String promptKey, String version,
        String label, String md5)
        throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter `promptKey` not present");
        }
        PromptVersionInfo result =
            promptOperationService.queryPrompt(namespaceId, promptKey, version, label);
        String currentMd5 = result.getMd5();
        if (StringUtils.isNotBlank(md5) && md5.equals(currentMd5)) {
            throw new NacosException(NacosException.NOT_MODIFIED, "prompt data is up to date");
        }
        return result;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Always pass a non-blank promptKey to queryPrompt.
2. Validate the key is set at SDK construction or before the query call.
3. Default to a known key or fail fast in client code if the source of the key is empty.
4. Log the inbound parameters at the gateway/controller to detect upstream field loss.

Example fix

// before
promptClientService.queryPrompt(ns, "", ver, label, md5); // 400
// after
if (promptKey == null || promptKey.isBlank()) {
    throw new IllegalArgumentException("promptKey is required");
}
promptClientService.queryPrompt(ns, promptKey, ver, label, md5);

// Validate promptKey before the SDK query
if (promptKey == null || promptKey.isBlank()) {
    throw new IllegalArgumentException("promptKey is required");
}
promptClientService.queryPrompt(namespaceId, promptKey, version, label, md5);

private static boolean isNotBlank(String s) {
    return s != null && !s.trim().isEmpty();
}

try {
    result = promptClientService.queryPrompt(ns, key, ver, label, md5);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.PARAMETER_MISSING.getCode()) {
        // prompt user to select a prompt key
    } else { throw e; }
}

When it happens

Trigger: SDK queryPrompt call with promptKey null/empty/whitespace; client binding that failed to populate the key; URL/form parameter stripped by encoding.

Common situations: Misconfigured SDK client where the key comes from an empty config property; UI search before a prompt is selected; programmatic loop that passes an uninitialized variable.

Related errors

• PARAMETER_MISSING
• 10000
• PARAMETER_MISSING
• 10000
• 10000

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