{"record":{"id":"d069a7fa640b490c","repo":"alibaba/nacos","slug":"20002-d069a7","errorCode":"20002","errorMessage":"Invalid version from {source}: '{version}', expected x.y.z or vN","messagePattern":"Invalid version from (.+?): '(.+?)', expected x\\.y\\.z or vN","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/skills/SkillOperationServiceImpl.java","lineNumber":690,"sourceCode":"        SkillResource metaResource = skill.getResource().get(resourceId);\n        if (metaResource == null || StringUtils.isBlank(metaResource.getContent())) {\n            return null;\n        }\n        try {\n            @SuppressWarnings(\"unchecked\")\n            Map<String, Object> meta = JacksonUtils.toObj(metaResource.getContent(), Map.class);\n            Object version = meta == null ? null : meta.get(\"version\");\n            return version == null ? null : StringUtils.trim(String.valueOf(version));\n        } catch (Exception e) {\n            LOGGER.warn(\"Failed to resolve version from skill _meta.json: {}\", e.getMessage());\n            return null;\n        }\n    }\n    \n    private static String validateUploadVersionFormat(String version, String source)\n        throws NacosApiException {\n        if (!VersionUtils.isSupportedVersionFormat(version)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Invalid version from \" + source + \": '\" + version\n                    + \"', expected x.y.z or vN\");\n        }\n        return version;\n    }\n    \n    private static UploadVersionCandidate buildLenientUploadVersionCandidate(String version,\n        String source) {\n        String candidate = StringUtils.trim(version);\n        if (VersionUtils.isSupportedVersionFormat(candidate)) {\n            return new UploadVersionCandidate(candidate, source);\n        }\n        String normalizedVersion = normalizeShortSemverVersion(candidate);\n        if (normalizedVersion != null) {\n            return UploadVersionCandidate.normalized(normalizedVersion, source, candidate);\n        }\n        return UploadVersionCandidate.invalid(candidate, source);","sourceCodeStart":672,"sourceCodeEnd":708,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/skills/SkillOperationServiceImpl.java#L672-L708","documentation":"An INVALID_PARAM (HTTP 400, ErrorCode PARAMETER_VALIDATE_ERROR/20002) from validateUploadVersionFormat: the version resolved from a source (SKILL.md YAML front-matter, or _meta.json inside the ZIP) is not a supported format. Supported formats are full semantic version x.y.z (e.g. 1.0.0) or the legacy vN form (e.g. v3). Short forms like 1.0 are only accepted on the lenient/normalized path, not the strict validation path.","triggerScenarios":"Uploading a skill whose front-matter / _meta.json declares a version like '1.0', 'latest', a date, or any non-x.y.z/non-vN string, when the strict version resolution path is taken.","commonSituations":"Author used a short semver (1.0 / 1) expecting it to be accepted; used a tag like 'latest' or 'stable'; non-numeric or date-based versioning.","solutions":["Set the version to a full x.y.z value (e.g. 1.0.0) or a vN value (e.g. v3) in SKILL.md front-matter and/or _meta.json.","Remove the version field to let the server fall back to the default 0.0.1 / auto-increment.","Re-zip and re-upload."],"exampleFix":"// before — SKILL.md front-matter\n---\nname: weather-tool\nversion: 1.0\n---\n\n// after\n---\nname: weather-tool\nversion: 1.0.0\n---","handlingStrategy":"validation","validationCode":"// Validate the declared version format before uploading.\nString v = resolveVersionFromFrontmatter(skillMd);\nif (StringUtils.isNotBlank(v) && !VersionUtils.isSupportedVersionFormat(v)) {\n    // ask the author to use x.y.z or vN (or remove the field for default 0.0.1)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use full semver x.y.z (1.0.0) or vN (v3) in SKILL.md front-matter and _meta.json.","Avoid short forms (1.0), tags (latest), or date-based versions for the strict path.","Omit the version field to let the server default/auto-increment."],"tags":["upload","version","validation","semver","skill"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}