alibaba/nacos · error · NacosApiException

RESOURCE_CONFLICT

RESOURCE_CONFLICT

Error message

targetVersion already exists: {candidate}

What it means

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).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java:1190

        return DEFAULT_INITIAL_VERSION;
    }
    
    private String resolveSpecifiedDraftVersion(String namespaceId, String name,
        String targetVersion,
        String basedOnVersion, String baseVersion) throws NacosException {
        if (StringUtils.isBlank(targetVersion)) {
            return nextVersion(namespaceId, name);
        }
        String candidate = targetVersion.trim();
        if (!VersionUtils.isSupportedVersionFormat(candidate)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Invalid targetVersion format: " + candidate + ", expected x.y.z or vN");
        }
        List<String> existingVersions = resourceManager.listExistingVersions(namespaceId, name,
            RESOURCE_TYPE_AGENTSPEC);
        if (existingVersions.contains(candidate)) {
            throw new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
                "targetVersion already exists: " + candidate);
        }
        if (StringUtils.isNotBlank(basedOnVersion) && StringUtils.isNotBlank(baseVersion)) {
            boolean isGreater = VersionUtils.isGreaterVersion(candidate, baseVersion);
            if (!isGreater) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "targetVersion must be greater than basedOnVersion, basedOnVersion="
                        + baseVersion
                        + ", targetVersion=" + candidate);
            }
        }
        return candidate;
    }
    
    /**
     * Check whether the built-in AgentSpec content is missing critical data (e.g., main content or AGENTS.md).
     * Used by bootstrap repair logic to decide if re-writing is needed.

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Choose a new, unused targetVersion (bump patch/minor) before retrying.
  2. Omit targetVersion to let the server auto-resolve the next free version via nextVersion().
  3. Query existing versions first and pick one not in the set.
  4. Make the create idempotent by checking the conflict and treating it as success if the existing version matches intended content.

Example fix

// before
agentSpecService.createDraft(ns, name, null, "1.0.0"); // already exists -> 409
// after
List<String> existing = listVersions(ns, name);
String v = pickNextFree(existing, "1.0.0");
agentSpecService.createDraft(ns, name, null, v);
// or let server decide
agentSpecService.createDraft(ns, name, null, null);
Defensive patterns

Strategy: validation

Validate before calling

// Ensure targetVersion is not already used
List<String> existing = agentSpecService.listExistingVersions(ns, name);
String safe = (targetVersion != null && existing.contains(targetVersion))
    ? null : targetVersion; // fall back to server auto-assign
agentSpecService.createDraft(ns, name, basedOn, safe);

Try / catch

try {
    agentSpecService.createDraft(ns, name, basedOn, target);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {
        // bump or let server decide
        agentSpecService.createDraft(ns, name, basedOn, null);
    } else { throw e; }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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