alibaba/nacos · error · NacosApiException

NOT_FOUND

NOT_FOUND

Error message

Agent %s version %s not found.

What it means

Thrown by LegacyA2aOperationService.queryTargetVersion when the agent-version config (dataId = encodedName + '-' + version) is not found in the config store. This means the agent itself exists but the specific requested version does not. Uses ErrorCode.AGENT_VERSION_NOT_FOUND for distinction from agent-level not-found.

Solutions

1. List the agent's available versions first (listAgentVersions) and use an exact version string from the results.
2. Verify the version string matches exactly (case-sensitive, no extra whitespace, correct format).
3. If the version was deleted, publish it again or use the latest available version.

Example fix

// before
var detail = a2aService.getAgentCard(ns, agentName, "1.0", "");

// after
var versions = a2aService.listAgentVersions(ns, agentName);
String exactVersion = versions.stream()
    .map(AgentVersionSummary::getVersion)
    .filter(v -> v.startsWith("1.0"))
    .findFirst()
    .orElseThrow();
var detail = a2aService.getAgentCard(ns, agentName, exactVersion, "");

// List available versions before requesting a specific one
List<AgentVersionSummary> versions = a2aService.listAgentVersions(ns, agentName);
boolean exists = versions.stream().anyMatch(v -> version.equals(v.getVersion()));
if (!exists) {
    throw new IllegalArgumentException("Version not found: " + version);
}
a2aService.getAgentCard(ns, agentName, version, "");

public static boolean agentVersionExists(
        A2aOperationService svc, String ns, String name, String version) {
    return svc.listAgentVersions(ns, name).stream()
        .anyMatch(v -> version.equals(v.getVersion()));
}

try {
    a2aService.getAgentCard(ns, agentName, version, "");
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.AGENT_VERSION_NOT_FOUND.getCode()) {
        // fall back to latest version
        String latest = a2aService.getLatestVersion(ns, agentName);
        a2aService.getAgentCard(ns, agentName, latest, "");
    } else {
        throw e;
    }
}

When it happens

Trigger: Requesting a specific agent version that was never published, was deleted, or has a version string that does not match any persisted version dataId. Typo in the version string. Version was rolled back or pruned.

Common situations: Client requests version '1.0.0' but the published version is '1.0' or 'v1.0.0'. Version pruning removed old versions. Cross-environment confusion where a version exists in dev but not prod. Stale version reference cached after a rollback.

Understand the failure class

Background: NOT_FOUND error code: why tRPC, Harbor, Nacos and other libraries return 404 "not found" errors for resources that may still exist — this error's family across 11 libraries.

Related errors

• 50100
• NOT_FOUND
• PARAMETER_VALIDATE_ERROR
• 10000
• 20002

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

Appendix: source

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

                        ErrorCode.AGENT_VERSION_NOT_FOUND,
                        String.format("Agent %s latest version not found",
                            agentCardVersionInfo.getName())))
                .getVersion();
        return queryTargetVersion(agentCardVersionInfo, latestVersion, namespaceId,
            registrationType);
    }
    
    private AgentCardDetailInfo queryTargetVersion(AgentCardVersionInfo agentCardVersionInfo,
        String version,
        String namespaceId, String registrationType) throws NacosApiException {
        String versionDataId =
            agentIdCodecHolder.encode(agentCardVersionInfo.getName()) + "-" + version;
        ConfigQueryChainRequest request =
            ConfigQueryChainRequest.buildConfigQueryChainRequest(versionDataId,
                AGENT_VERSION_GROUP, namespaceId);
        ConfigQueryChainResponse response = configQueryChainService.handle(request);
        if (response.getStatus() == ConfigQueryChainResponse.ConfigQueryStatus.CONFIG_NOT_FOUND) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.AGENT_VERSION_NOT_FOUND,
                String.format("Agent %s version %s not found.", agentCardVersionInfo.getName(),
                    version));
        }
        AgentCardDetailInfo result =
            JacksonUtils.toObj(response.getContent(), AgentCardDetailInfo.class);
        if (!AgentRequestUtil.isAgentCardNormalized(result)) {
            AgentRequestUtil.normalizeAgentCard(result);
        }
        if (StringUtils.isBlank(registrationType)) {
            registrationType = result.getRegistrationType();
        }
        if (AiConstants.A2a.A2A_ENDPOINT_TYPE_SERVICE.equalsIgnoreCase(registrationType)) {
            injectEndpoint(result, namespaceId);
        }
        if (StringUtils.equals(agentCardVersionInfo.getLatestPublishedVersion(),
            result.getVersion())) {
            result.setLatestVersion(true);
        }

View on GitHub (pinned to 9b989acdf1)