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.

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)

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.

Related errors

• 50100
• NOT_FOUND
• PARAMETER_VALIDATE_ERROR
• CONFLICT
• 10000

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