alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'version' type String is not present

What it means

PromptOnlineForm.validate() requires a `version` field because toggling a prompt online/offline operates on a specific published version, not the prompt as a whole. `super.validate()` runs first (validating the promptKey base fields), then this check fails fast with PARAMETER_MISSING if version is blank, so the server never attempts to flip state on an unspecified version.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/prompt/PromptOnlineForm.java:42

import java.io.Serial;

/**
 * Prompt online/offline form.
 *
 * @author nacos
 */
public class PromptOnlineForm extends PromptForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    private String version;
    
    @Override
    public void validate() throws NacosApiException {
        super.validate();
        if (StringUtils.isBlank(version)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter 'version' type String is not present");
        }
    }
    
    public String getVersion() {
        return version;
    }
    
    public void setVersion(String version) {
        this.version = version;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Add `version` in major.minor.patch form (e.g. `1.0.0`) to the request.
Fetch the list of published versions first to identify the correct version string to toggle.
If your UI means 'toggle the latest version', resolve the latest version server-side first and then send that explicit version.

Example fix

// before
{"promptKey":"hello","namespaceId":"public"}
// after
{"promptKey":"hello","namespaceId":"public","version":"1.0.0"}

Defensive patterns

Strategy: validation

Validate before calling

// Before calling prompt online/offline
if (version == null || version.isBlank()) {
    throw new IllegalArgumentException("version is required for prompt online/offline");
}

Type guard

// TypeScript
const hasVersion = (v?: string | null): boolean =>
  v != null && v.trim().length > 0;

Try / catch

try {
    form.validate();
} catch (NacosApiException e) {
    // PARAMETER_MISSING for version — prompt user to select a version
}

Prevention

Resolve the latest version from the list API before enabling the online/offline button.
Disable the toggle button in the UI until a version is selected.
Make version a required field in the request DTO with a non-null constraint.

When it happens

Trigger: Calling the prompt online or offline API (e.g. PUT /v3/admin/ai/prompts/online) with the `version` field missing, empty, or whitespace-only. Required because the operation is version-scoped.

Common situations: Assuming online/offline applies to the latest version automatically and omitting `version`; passing only `promptKey`; frontend form that sends a draft/unpublished version string that resolves to empty; version field name typo in the request body.

Related errors

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