alibaba/nacos · error · NacosApiException

50100

50100

Error message

Agent not found: %s

What it means

Thrown by LegacyA2aOperationService.queryAgentCardVersionInfo when the agent-level config (dataId = encoded name, group = AGENT_GROUP) returns CONFIG_NOT_FOUND. This means no agent with that name exists at all in the namespace — as opposed to error 112 where the agent exists but a specific version does not. Uses ErrorCode.AGENT_NOT_FOUND.

Source

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

        configForm.setContent(JacksonUtils.toJson(storageInfo));
        configForm.setConfigTags("nacos.internal.config=agent-version");
        configForm.setAppName(storageInfo.getName());
        configForm.setSrcUser("nacos");
        configForm.setType(ConfigType.JSON.getType());
        
        return configForm;
    }
    
    private AgentCardVersionInfo queryAgentCardVersionInfo(String namespaceId, String name)
        throws NacosApiException {
        // Check if the agent exists
        String actualDataId = agentIdCodecHolder.encode(name);
        ConfigQueryChainRequest request =
            ConfigQueryChainRequest.buildConfigQueryChainRequest(actualDataId,
                AGENT_GROUP, namespaceId);
        ConfigQueryChainResponse response = configQueryChainService.handle(request);
        if (response.getStatus() == ConfigQueryChainResponse.ConfigQueryStatus.CONFIG_NOT_FOUND) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.AGENT_NOT_FOUND,
                "Agent not found: " + name);
        }
        return JacksonUtils.toObj(response.getContent(), AgentCardVersionInfo.class);
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. List agents in the target namespace to confirm the name exists before operating on it.
2. Verify the namespaceId matches where the agent was created.
3. If the agent was deleted, create it first via releaseAgent/registerAgent.
4. Check for typos or encoding issues in the agent name (names are encoded via agentIdCodecHolder).

Example fix

// before
var card = a2aService.getAgentCard(ns, "my-agnet", version, ""); // typo

// after
var agents = a2aService.listAgents(ns, "my-agen", ...);
String exactName = agents.stream()
    .map(AgentSummary::getName)
    .filter(n -> n.startsWith("my-agen"))
    .findFirst()
    .orElseThrow();
var card = a2aService.getAgentCard(ns, exactName, version, "");

// Verify the agent exists before operating on it
try {
    a2aService.getAgentCard(ns, agentName, StringUtils.EMPTY, StringUtils.EMPTY);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.AGENT_NOT_FOUND.getCode()) {
        // agent does not exist — create first or surface error
        throw new IllegalStateException("Agent not found, create it first: " + agentName);
    }
}

public static boolean agentExists(
        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 {
    a2aService.getAgentCard(ns, agentName, version, "");
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.AGENT_NOT_FOUND.getCode()) {
        // agent missing — create it first, then retry
        a2aService.releaseAgent(agentCard, ns, registrationType, true);
        a2aService.getAgentCard(ns, agentName, version, "");
    } else {
        throw e;
    }
}

When it happens

Trigger: Requesting any operation on an agent name that was never created, was fully deleted (all versions removed), or exists in a different namespace. Calling getAgentCard, updateAgentCard, or deleteAgentCard for a non-existent name.

Common situations: Namespace mismatch. Agent was deleted by another process. Typo in agent name. Cross-environment confusion. Stale reference to an agent that was cleaned up.

Related errors

• NOT_FOUND
• NOT_FOUND
• CONFLICT
• 10000
• Agent Version namespaceId does not match request

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