{"record":{"id":"15f68fffe754bac5","repo":"alibaba/nacos","slug":"20002-15f68f","errorCode":"20002","errorMessage":"Version must be in format major.minor.patch, got: {version}","messagePattern":"Version must be in format major\\.minor\\.patch, got: (.+?)","errorType":"exception","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/prompt/PromptOperationServiceImpl.java","lineNumber":935,"sourceCode":"    }\n    \n    private void updateMetaBizTagsCas(String namespaceId, AiResource meta, String bizTags)\n        throws NacosException {\n        resourceManager.updateBizTagsCas(namespaceId, meta, bizTags);\n    }\n    \n    private void updateMetaDescriptionCas(String namespaceId, AiResource meta, String description)\n        throws NacosException {\n        if (meta == null || meta.getMetaVersion() == null) {\n            throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,\n                \"Meta version missing\");\n        }\n        resourceManager.bumpMetaDescription(namespaceId, meta, description);\n    }\n    \n    private void validateVersion(String version) throws NacosApiException {\n        if (!PromptVersionUtils.isValidVersion(version)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Version must be in format major.minor.patch, got: \" + version);\n        }\n    }\n    \n    /**\n     * Load all version rows for a prompt by paginating through all pages.\n     */\n    private List<AiResourceVersion> loadAllVersionRows(String namespaceId, String promptKey) {\n        List<AiResourceVersion> all = new ArrayList<>();\n        int pageNo = 1;\n        int pageSize = 200;\n        while (true) {\n            Page<AiResourceVersion> page = resourceManager.listVersions(namespaceId, promptKey,\n                RESOURCE_TYPE_PROMPT, null, pageNo, pageSize);\n            if (page == null || page.getPageItems() == null || page.getPageItems().isEmpty()) {\n                break;\n            }","sourceCodeStart":917,"sourceCodeEnd":953,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/prompt/PromptOperationServiceImpl.java#L917-L953","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Format the version as exactly three numeric dot-separated segments: major.minor.patch (e.g. 1.0.0).","Strip any 'v' prefix or build metadata before passing to the API.","If you want auto-numbering, omit targetVersion and let the server call resolveNextVersion to assign the next patch increment."],"exampleFix":"// before\nservice.createDraft(ns, key, null, \"v1.0\", template, vars, null);\n\n// after\nservice.createDraft(ns, key, null, \"1.0.0\", template, vars, null);\n// or omit targetVersion for auto-increment\nservice.createDraft(ns, key, null, null, template, vars, null);","handlingStrategy":"validation","validationCode":"// Validate version format before API call\nprivate static final Pattern VERSION = Pattern.compile(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+$\");\nif (!VERSION.matcher(targetVersion).matches()) {\n    throw new IllegalArgumentException(\"Version must be major.minor.patch\");\n}\nservice.createDraft(ns, key, basedOn, targetVersion, template, vars, msg);","typeGuard":"boolean isValidSemver = targetVersion != null\n    && Pattern.compile(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+$\").matcher(targetVersion).matches();","tryCatchPattern":"try {\n    service.createDraft(ns, key, basedOn, targetVersion, template, vars, msg);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()) {\n        // fix version format and retry\n    }\n    throw e;\n}","preventionTips":["Enforce the major.minor.patch format in client-side form validation before submitting.","Omit targetVersion to use server-side auto-increment (resolveNextVersion) which always produces valid versions.","Strip 'v' prefixes and pre-release suffixes from version strings before API calls."],"tags":["prompt","validation","ai-registry","version-format"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}