alibaba/nacos · error · NacosApiException
20005
20005
Error message
Meta update conflict, retry
What it means
Thrown by handleStrictCasResult when doCasLoop returns CasResult.MAX_RETRIES — all MAX_WORKING_VERSION_RETRY (3) attempts to updateMetaCas failed due to continuous version conflicts. HTTP 409 RESOURCE_CONFLICT (code 20005). This means another writer updated the same resource meta on every retry attempt.
Source
Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/resource/AiResourceManager.java:155
if (latest == null || latest.getMetaVersion() == null) {
return CasResult.META_LOST;
}
expected = latest.getMetaVersion();
onConflictRefresh.accept(newValue, latest);
}
return CasResult.MAX_RETRIES;
}
/**
* Translate a non-SUCCESS CasResult into the appropriate exception for strict callers.
*/
private void handleStrictCasResult(CasResult result) throws NacosException {
if (result == CasResult.META_LOST) {
throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,
"Meta cas failed");
}
if (result == CasResult.MAX_RETRIES) {
throw new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
"Meta update conflict, retry");
}
}
/**
* CAS-update the versionInfo field of a resource meta row.
*/
public void updateVersionInfoCas(String namespaceId, AiResource meta, ResourceVersionInfo info)
throws NacosException {
if (meta == null || meta.getMetaVersion() == null) {
throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,
"Meta version missing");
}
AiResource newValue = buildVersionInfoUpdateValue(meta, info);
CasResult result =
doCasLoop(namespaceId, meta.getName(), meta.getType(), meta.getMetaVersion(), newValue,
(nv, latest) -> {
nv.setStatus(latest.getStatus());View on GitHub (pinned to 9b989acdf1)
Solutions
- Reduce write concurrency on the same resource — serialize or throttle updates.
- Retry the entire operation with backoff after catching the CONFLICT exception.
- Split large batch updates into smaller sequential operations.
- If the workload is inherently concurrent, consider increasing MAX_WORKING_VERSION_RETRY (requires code change and testing).
Example fix
// before: unguarded concurrent update
resourceManager.updateVersionInfoCas(ns, meta, info);
// after: retry with backoff on conflict
for (int attempt = 0; attempt < 5; attempt++) {
try {
AiResource fresh = resourceManager.requireMeta(ns, name, type);
resourceManager.updateVersionInfoCas(ns, fresh, info);
break;
} catch (NacosApiException e) {
if (e.getErrCode() != NacosException.CONFLICT || attempt == 4) throw e;
Thread.sleep(100L * (attempt + 1));
}
} Defensive patterns
Strategy: retry
Validate before calling
// Pre-check: reduce concurrency on the target resource before updating // (no code-level pre-check can prevent this — it requires workload design)
Try / catch
for (int attempt = 0; attempt < 5; attempt++) {
try {
AiResource fresh = resourceManager.requireMeta(ns, name, type);
resourceManager.updateBizTagsCas(ns, fresh, tags);
break;
} catch (NacosApiException e) {
if (e.getErrCode() == NacosException.CONFLICT && attempt < 4) {
Thread.sleep(100L * (attempt + 1));
continue;
}
throw e;
}
} Prevention
- Serialize or throttle concurrent writes to the same resource meta row.
- Batch multiple field changes into a single CAS update rather than many small ones.
- Monitor CAS contention metrics and scale horizontally (more resources) or reduce write frequency.
When it happens
Trigger: High-concurrency writes to the same resource meta row: multiple requests simultaneously updating versionInfo or bizTags. Each failed CAS triggers a re-read and retry, but if 3 consecutive attempts all lose the race, this exception fires.
Common situations: Burst of concurrent publish/label/draft operations on the same prompt or agent; a batch job updating many versions of one resource in parallel; distributed clients racing on the same resource.
Related errors
AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14).
Data as JSON: /api/errors/a231a06e12254780.
Report an issue: GitHub.