{"record":{"id":"20b0a13c464aeed4","repo":"alibaba/nacos","slug":"not-found-20b0a1","errorCode":"NOT_FOUND","errorMessage":"Agent %s version %s not found.","messagePattern":"Agent (.+?) version (.+?) not found\\.","errorType":"exception","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java","lineNumber":442,"sourceCode":"                        ErrorCode.AGENT_VERSION_NOT_FOUND,\n                        String.format(\"Agent %s latest version not found\",\n                            agentCardVersionInfo.getName())))\n                .getVersion();\n        return queryTargetVersion(agentCardVersionInfo, latestVersion, namespaceId,\n            registrationType);\n    }\n    \n    private AgentCardDetailInfo queryTargetVersion(AgentCardVersionInfo agentCardVersionInfo,\n        String version,\n        String namespaceId, String registrationType) throws NacosApiException {\n        String versionDataId =\n            agentIdCodecHolder.encode(agentCardVersionInfo.getName()) + \"-\" + version;\n        ConfigQueryChainRequest request =\n            ConfigQueryChainRequest.buildConfigQueryChainRequest(versionDataId,\n                AGENT_VERSION_GROUP, namespaceId);\n        ConfigQueryChainResponse response = configQueryChainService.handle(request);\n        if (response.getStatus() == ConfigQueryChainResponse.ConfigQueryStatus.CONFIG_NOT_FOUND) {\n            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.AGENT_VERSION_NOT_FOUND,\n                String.format(\"Agent %s version %s not found.\", agentCardVersionInfo.getName(),\n                    version));\n        }\n        AgentCardDetailInfo result =\n            JacksonUtils.toObj(response.getContent(), AgentCardDetailInfo.class);\n        if (!AgentRequestUtil.isAgentCardNormalized(result)) {\n            AgentRequestUtil.normalizeAgentCard(result);\n        }\n        if (StringUtils.isBlank(registrationType)) {\n            registrationType = result.getRegistrationType();\n        }\n        if (AiConstants.A2a.A2A_ENDPOINT_TYPE_SERVICE.equalsIgnoreCase(registrationType)) {\n            injectEndpoint(result, namespaceId);\n        }\n        if (StringUtils.equals(agentCardVersionInfo.getLatestPublishedVersion(),\n            result.getVersion())) {\n            result.setLatestVersion(true);\n        }","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java#L424-L460","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["List the agent's available versions first (listAgentVersions) and use an exact version string from the results.","Verify the version string matches exactly (case-sensitive, no extra whitespace, correct format).","If the version was deleted, publish it again or use the latest available version."],"exampleFix":"// before\nvar detail = a2aService.getAgentCard(ns, agentName, \"1.0\", \"\");\n\n// after\nvar versions = a2aService.listAgentVersions(ns, agentName);\nString exactVersion = versions.stream()\n    .map(AgentVersionSummary::getVersion)\n    .filter(v -> v.startsWith(\"1.0\"))\n    .findFirst()\n    .orElseThrow();\nvar detail = a2aService.getAgentCard(ns, agentName, exactVersion, \"\");","handlingStrategy":"validation","validationCode":"// List available versions before requesting a specific one\nList<AgentVersionSummary> versions = a2aService.listAgentVersions(ns, agentName);\nboolean exists = versions.stream().anyMatch(v -> version.equals(v.getVersion()));\nif (!exists) {\n    throw new IllegalArgumentException(\"Version not found: \" + version);\n}\na2aService.getAgentCard(ns, agentName, version, \"\");","typeGuard":"public static boolean agentVersionExists(\n        A2aOperationService svc, String ns, String name, String version) {\n    return svc.listAgentVersions(ns, name).stream()\n        .anyMatch(v -> version.equals(v.getVersion()));\n}","tryCatchPattern":"try {\n    a2aService.getAgentCard(ns, agentName, version, \"\");\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.AGENT_VERSION_NOT_FOUND.getCode()) {\n        // fall back to latest version\n        String latest = a2aService.getLatestVersion(ns, agentName);\n        a2aService.getAgentCard(ns, agentName, latest, \"\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Use exact version strings from listAgentVersions results.","Do not hardcode version strings — fetch them dynamically.","Handle version pruning/rollback by refreshing version lists."],"tags":["a2a","agent","not-found","version","config-query"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}