What causes "AgentCard name %s already exist" in alibaba/nacos?

Use releaseAgent instead of registerAgent — it checks for existence and routes to create or update automatically.

alibaba/nacos · error · NacosApiException

CONFLICT

CONFLICT

Error message

AgentCard name %s already exist

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java:128

            configOperationService.publishConfig(configForm, versionConfigRequest, null);
            
            // 2. register agent's version info
            AgentCardDetailInfo agentCardDetailInfo =
                AgentCardUtil.buildAgentCardDetailInfo(agentCard,
                    registrationType);
            ConfigForm configFormVersion =
                transferAgentInfoToConfigForm(agentCardDetailInfo, namespaceId);
            ConfigRequestInfo agentCardConfigRequest = new ConfigRequestInfo();
            agentCardConfigRequest.setUpdateForExist(Boolean.FALSE);
            long startOperationTime = System.currentTimeMillis();
            configOperationService.publishConfig(configFormVersion, agentCardConfigRequest, null);
            
            syncEffectService.toSync(configFormVersion, startOperationTime);
            AiResourceTraceService.logSuccess("a2a", agentCard.getName(), agentCard.getVersion(),
                AiResourceTraceService.OP_CREATE_DRAFT, VisibilityHelper.resolveCurrentIdentity(),
                VisibilityHelper.resolveClientIp());
        } catch (ConfigAlreadyExistsException e) {
            throw new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
                String.format("AgentCard name %s already exist", agentCard.getName()));
        }
    }
    
    /**
     * Release one AgentCard using the historical create-or-add-version behavior.
     *
     * @param agentCard AgentCard definition
     * @param namespaceId namespace identifier
     * @param registrationType registration type
     * @param setAsLatest whether to move the latest pointer for a new Version
     * @throws NacosException when release fails
     */
    @Override
    public void releaseAgent(AgentCard agentCard, String namespaceId, String registrationType,
        boolean setAsLatest) throws NacosException {
        try {
            getAgentCard(namespaceId, agentCard.getName(), agentCard.getVersion(),

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// before
a2aService.registerAgent(agentCard, ns, registrationType);

// after — use releaseAgent which handles create-or-update
a2aService.releaseAgent(agentCard, ns, registrationType, true);

Defensive patterns

Strategy: try-catch

Validate before calling

// Use releaseAgent (create-or-update) instead of registerAgent (create-only)
a2aService.releaseAgent(agentCard, ns, registrationType, true);

Type guard

public static boolean agentCardExists(
        A2aOperationService svc, String ns, String name) {
    try {
        svc.getAgentCard(ns, name, StringUtils.EMPTY, StringUtils.EMPTY);
        return true;
    } catch (NacosApiException e) {
        return e.getDetailErrCode() != ErrorCode.AGENT_NOT_FOUND.getCode();
    }
}

Try / catch

try {
    a2aService.registerAgent(agentCard, ns, registrationType);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {
        // already exists — update instead
        a2aService.updateAgentCard(agentCard, ns, registrationType, true);
    } else {
        throw e;
    }
}

Prevention

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.

When it happens

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

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

Related errors

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