{"record":{"id":"2d67f3966325a243","repo":"alibaba/nacos","slug":"resource-conflict","errorCode":"RESOURCE_CONFLICT","errorMessage":"targetVersion already exists: {candidate}","messagePattern":"targetVersion already exists: (.+?)","errorType":"http","errorClass":"NacosApiException","httpStatus":409,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java","lineNumber":1190,"sourceCode":"        return DEFAULT_INITIAL_VERSION;\n    }\n    \n    private String resolveSpecifiedDraftVersion(String namespaceId, String name,\n        String targetVersion,\n        String basedOnVersion, String baseVersion) throws NacosException {\n        if (StringUtils.isBlank(targetVersion)) {\n            return nextVersion(namespaceId, name);\n        }\n        String candidate = targetVersion.trim();\n        if (!VersionUtils.isSupportedVersionFormat(candidate)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Invalid targetVersion format: \" + candidate + \", expected x.y.z or vN\");\n        }\n        List<String> existingVersions = resourceManager.listExistingVersions(namespaceId, name,\n            RESOURCE_TYPE_AGENTSPEC);\n        if (existingVersions.contains(candidate)) {\n            throw new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,\n                \"targetVersion already exists: \" + candidate);\n        }\n        if (StringUtils.isNotBlank(basedOnVersion) && StringUtils.isNotBlank(baseVersion)) {\n            boolean isGreater = VersionUtils.isGreaterVersion(candidate, baseVersion);\n            if (!isGreater) {\n                throw new NacosApiException(NacosException.INVALID_PARAM,\n                    ErrorCode.PARAMETER_VALIDATE_ERROR,\n                    \"targetVersion must be greater than basedOnVersion, basedOnVersion=\"\n                        + baseVersion\n                        + \", targetVersion=\" + candidate);\n            }\n        }\n        return candidate;\n    }\n    \n    /**\n     * Check whether the built-in AgentSpec content is missing critical data (e.g., main content or AGENTS.md).\n     * Used by bootstrap repair logic to decide if re-writing is needed.","sourceCodeStart":1172,"sourceCodeEnd":1208,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java#L1172-L1208","documentation":"Thrown by AgentSpecOperationServiceImpl.resolveSpecifiedDraftVersion when the targetVersion passes format validation but already exists in the list of existing versions for that agentspec. Version strings must be unique per resource. Reported as RESOURCE_CONFLICT (HTTP 409).","triggerScenarios":"Passing a targetVersion that equals an already-stored (draft, released, or any status) version for the same agentspec name; re-running an idempotent create after a partial success; hardcoded version in CI that collides on the second run.","commonSituations":"Pinned versions in automation that re-run; client retrying after a timeout when the first call actually succeeded; release workflow re-using a version tag; concurrent createDraft calls racing to claim the same version.","solutions":["Choose a new, unused targetVersion (bump patch/minor) before retrying.","Omit targetVersion to let the server auto-resolve the next free version via nextVersion().","Query existing versions first and pick one not in the set.","Make the create idempotent by checking the conflict and treating it as success if the existing version matches intended content."],"exampleFix":"// before\nagentSpecService.createDraft(ns, name, null, \"1.0.0\"); // already exists -> 409\n// after\nList<String> existing = listVersions(ns, name);\nString v = pickNextFree(existing, \"1.0.0\");\nagentSpecService.createDraft(ns, name, null, v);\n// or let server decide\nagentSpecService.createDraft(ns, name, null, null);","handlingStrategy":"validation","validationCode":"// Ensure targetVersion is not already used\nList<String> existing = agentSpecService.listExistingVersions(ns, name);\nString safe = (targetVersion != null && existing.contains(targetVersion))\n    ? null : targetVersion; // fall back to server auto-assign\nagentSpecService.createDraft(ns, name, basedOn, safe);","typeGuard":null,"tryCatchPattern":"try {\n    agentSpecService.createDraft(ns, name, basedOn, target);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {\n        // bump or let server decide\n        agentSpecService.createDraft(ns, name, basedOn, null);\n    } else { throw e; }\n}","preventionTips":["Query existing versions before choosing targetVersion.","Prefer server-assigned versions (omit targetVersion) in automated flows.","Make create requests idempotent by checking conflict and comparing content."],"tags":["agentspec","resource-conflict","version","duplicate","nacos-ai"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}