{"record":{"id":"59c14b6200d3b222","repo":"alibaba/nacos","slug":"conflict-59c14b","errorCode":"CONFLICT","errorMessage":"AgentCard name %s already exist","messagePattern":"AgentCard name (.+?) already exist","errorType":"exception","errorClass":"NacosApiException","httpStatus":409,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java","lineNumber":128,"sourceCode":"            configOperationService.publishConfig(configForm, versionConfigRequest, null);\n            \n            // 2. register agent's version info\n            AgentCardDetailInfo agentCardDetailInfo =\n                AgentCardUtil.buildAgentCardDetailInfo(agentCard,\n                    registrationType);\n            ConfigForm configFormVersion =\n                transferAgentInfoToConfigForm(agentCardDetailInfo, namespaceId);\n            ConfigRequestInfo agentCardConfigRequest = new ConfigRequestInfo();\n            agentCardConfigRequest.setUpdateForExist(Boolean.FALSE);\n            long startOperationTime = System.currentTimeMillis();\n            configOperationService.publishConfig(configFormVersion, agentCardConfigRequest, null);\n            \n            syncEffectService.toSync(configFormVersion, startOperationTime);\n            AiResourceTraceService.logSuccess(\"a2a\", agentCard.getName(), agentCard.getVersion(),\n                AiResourceTraceService.OP_CREATE_DRAFT, VisibilityHelper.resolveCurrentIdentity(),\n                VisibilityHelper.resolveClientIp());\n        } catch (ConfigAlreadyExistsException e) {\n            throw new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,\n                String.format(\"AgentCard name %s already exist\", agentCard.getName()));\n        }\n    }\n    \n    /**\n     * Release one AgentCard using the historical create-or-add-version behavior.\n     *\n     * @param agentCard AgentCard definition\n     * @param namespaceId namespace identifier\n     * @param registrationType registration type\n     * @param setAsLatest whether to move the latest pointer for a new Version\n     * @throws NacosException when release fails\n     */\n    @Override\n    public void releaseAgent(AgentCard agentCard, String namespaceId, String registrationType,\n        boolean setAsLatest) throws NacosException {\n        try {\n            getAgentCard(namespaceId, agentCard.getName(), agentCard.getVersion(),","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java#L110-L146","documentation":"Thrown by LegacyA2aOperationService.registerAgent when configOperationService.publishConfig throws ConfigAlreadyExistsException, meaning the agent-card or agent-version config already exists for that name. The create flow uses UpdateForExist=FALSE, so publishing over an existing config triggers this CONFLICT. The caller should use the release/update flow instead.","triggerScenarios":"Calling registerAgent (create) for an agent name that already has a persisted AgentCard in the namespace. Re-running a create after a prior successful create. Using registerAgent instead of releaseAgent which handles create-or-add-version logic.","commonSituations":"Idempotent create script re-run after partial success. Team member already created the agent. CI pipeline retries a failed step that actually succeeded on the server. Confusion between registerAgent (create-only) and releaseAgent (create-or-update).","solutions":["Use releaseAgent instead of registerAgent — it checks for existence and routes to create or update automatically.","If the agent already exists and you want a new version, use updateAgentCard or the add-version flow.","Before registering, check if the agent exists (getAgentCard) and branch to update if it does."],"exampleFix":"// before\na2aService.registerAgent(agentCard, ns, registrationType);\n\n// after — use releaseAgent which handles create-or-update\na2aService.releaseAgent(agentCard, ns, registrationType, true);","handlingStrategy":"try-catch","validationCode":"// Use releaseAgent (create-or-update) instead of registerAgent (create-only)\na2aService.releaseAgent(agentCard, ns, registrationType, true);","typeGuard":"public static boolean agentCardExists(\n        A2aOperationService svc, String ns, String name) {\n    try {\n        svc.getAgentCard(ns, name, StringUtils.EMPTY, StringUtils.EMPTY);\n        return true;\n    } catch (NacosApiException e) {\n        return e.getDetailErrCode() != ErrorCode.AGENT_NOT_FOUND.getCode();\n    }\n}","tryCatchPattern":"try {\n    a2aService.registerAgent(agentCard, ns, registrationType);\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {\n        // already exists — update instead\n        a2aService.updateAgentCard(agentCard, ns, registrationType, true);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Prefer releaseAgent over registerAgent for idempotent create-or-update semantics.","Check agent existence before calling registerAgent.","In CI, make create idempotent to survive re-runs."],"tags":["a2a","agent","conflict","duplicate","create","config"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}