alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

promptKey is required

What it means

Thrown by PromptOperationServiceImpl.createDraft (admin path) when promptKey is blank. promptKey is the primary identifier for creating/publishing a prompt draft. Reported as PARAMETER_MISSING (HTTP 400).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/prompt/PromptOperationServiceImpl.java:135

    
    @Autowired(required = false)
    public void setAiResourceIndexMaintenanceService(
        AiResourceIndexMaintenanceService resourceIndexMaintenanceService) {
        if (resourceIndexMaintenanceService != null) {
            this.resourceIndexMaintenanceService = resourceIndexMaintenanceService;
        }
    }
    
    // ========== Admin APIs ==========
    
    @Override
    public String createDraft(String namespaceId, String promptKey, String basedOnVersion,
        String targetVersion,
        String template, List<PromptVariable> variables, String commitMsg, String description,
        String bizTags)
        throws NacosException {
        if (StringUtils.isBlank(promptKey)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "promptKey is required");
        }
        
        AiResource meta = resourceManager.findMeta(namespaceId, promptKey, RESOURCE_TYPE_PROMPT);
        
        if (meta == null) {
            // Brand-new prompt: require template
            if (StringUtils.isBlank(template)) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_MISSING,
                    "template is required when creating a new prompt");
            }
            String version =
                StringUtils.isBlank(targetVersion) ? DEFAULT_INITIAL_VERSION : targetVersion;
            validateVersion(version);
            
            String storageJson = writePromptToStorage(namespaceId, promptKey, version, template,
                variables, null);

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Supply a non-blank promptKey in the createDraft request.
  2. Validate the key client-side before the call.
  3. Generate a deterministic key (e.g. slugified name) if the user did not provide one.

Example fix

// before
promptService.createDraft(ns, null, ...); // 400
// after
String key = StringUtils.defaultIfBlank(promptKey, slugify(name));
promptService.createDraft(ns, key, ...);
Defensive patterns

Strategy: validation

Validate before calling

// Ensure promptKey is present before creating a draft
if (promptKey == null || promptKey.isBlank()) {
    throw new IllegalArgumentException("promptKey is required");
}
promptService.createDraft(ns, promptKey, basedOn, target, template, vars, msg, desc, tags);

Try / catch

try {
    promptService.createDraft(ns, key, basedOn, target, template, vars, msg, desc, tags);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.PARAMETER_MISSING.getCode()
        && e.getErrMsg().contains("promptKey")) {
        // require the user to provide a key
    } else { throw e; }
}

Prevention

When it happens

Trigger: POST create-prompt-draft with promptKey omitted, null, or whitespace-only.

Common situations: Form submission where the key field is empty; API client that did not set the key; automated script missing the key argument.

Related errors

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