alibaba/nacos · error · NacosApiException

20002

20002

Error message

Version must be in format major.minor.patch, got: {version}

What it means

Thrown by validateVersion when the version string does not match the pattern ^\d+\.\d+\.\d+$ (strict major.minor.patch with numeric segments). HTTP 400 PARAMETER_VALIDATE_ERROR (code 20002). Prompt versions follow semantic-style versioning with exactly three numeric dot-separated segments.

Source

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

    }
    
    private void updateMetaBizTagsCas(String namespaceId, AiResource meta, String bizTags)
        throws NacosException {
        resourceManager.updateBizTagsCas(namespaceId, meta, bizTags);
    }
    
    private void updateMetaDescriptionCas(String namespaceId, AiResource meta, String description)
        throws NacosException {
        if (meta == null || meta.getMetaVersion() == null) {
            throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,
                "Meta version missing");
        }
        resourceManager.bumpMetaDescription(namespaceId, meta, description);
    }
    
    private void validateVersion(String version) throws NacosApiException {
        if (!PromptVersionUtils.isValidVersion(version)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Version must be in format major.minor.patch, got: " + version);
        }
    }
    
    /**
     * Load all version rows for a prompt by paginating through all pages.
     */
    private List<AiResourceVersion> loadAllVersionRows(String namespaceId, String promptKey) {
        List<AiResourceVersion> all = new ArrayList<>();
        int pageNo = 1;
        int pageSize = 200;
        while (true) {
            Page<AiResourceVersion> page = resourceManager.listVersions(namespaceId, promptKey,
                RESOURCE_TYPE_PROMPT, null, pageNo, pageSize);
            if (page == null || page.getPageItems() == null || page.getPageItems().isEmpty()) {
                break;
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Format the version as exactly three numeric dot-separated segments: major.minor.patch (e.g. 1.0.0).
2. Strip any 'v' prefix or build metadata before passing to the API.
3. If you want auto-numbering, omit targetVersion and let the server call resolveNextVersion to assign the next patch increment.

Example fix

// before
service.createDraft(ns, key, null, "v1.0", template, vars, null);

// after
service.createDraft(ns, key, null, "1.0.0", template, vars, null);
// or omit targetVersion for auto-increment
service.createDraft(ns, key, null, null, template, vars, null);

// Validate version format before API call
private static final Pattern VERSION = Pattern.compile("^\\d+\\.\\d+\\.\\d+$");
if (!VERSION.matcher(targetVersion).matches()) {
    throw new IllegalArgumentException("Version must be major.minor.patch");
}
service.createDraft(ns, key, basedOn, targetVersion, template, vars, msg);

boolean isValidSemver = targetVersion != null
    && Pattern.compile("^\\d+\\.\\d+\\.\\d+$").matcher(targetVersion).matches();

try {
    service.createDraft(ns, key, basedOn, targetVersion, template, vars, msg);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()) {
        // fix version format and retry
    }
    throw e;
}

When it happens

Trigger: Calling createDraft or publish with a targetVersion like '1.0', 'v1.0.0', '1.0.0-beta', '1.0.0.0', or any non-numeric segment. The validation runs on every version before checking for conflicts or writing to storage.

Common situations: Client sends a shortened version (1.0 instead of 1.0.0); includes a 'v' prefix or pre-release suffix; uses a date-based version string; auto-increment logic produces an unexpected format.

Related errors

• 10000
• 10000
• 10000
• 10000
• 10000

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