{"record":{"id":"b876b9d825506154","repo":"alibaba/nacos","slug":"50100","errorCode":"50100","errorMessage":"Agent not found: %s","messagePattern":"Agent not found: (.+?)","errorType":"exception","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java","lineNumber":578,"sourceCode":"        configForm.setContent(JacksonUtils.toJson(storageInfo));\n        configForm.setConfigTags(\"nacos.internal.config=agent-version\");\n        configForm.setAppName(storageInfo.getName());\n        configForm.setSrcUser(\"nacos\");\n        configForm.setType(ConfigType.JSON.getType());\n        \n        return configForm;\n    }\n    \n    private AgentCardVersionInfo queryAgentCardVersionInfo(String namespaceId, String name)\n        throws NacosApiException {\n        // Check if the agent exists\n        String actualDataId = agentIdCodecHolder.encode(name);\n        ConfigQueryChainRequest request =\n            ConfigQueryChainRequest.buildConfigQueryChainRequest(actualDataId,\n                AGENT_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_NOT_FOUND,\n                \"Agent not found: \" + name);\n        }\n        return JacksonUtils.toObj(response.getContent(), AgentCardVersionInfo.class);\n    }\n}\n","sourceCodeStart":560,"sourceCodeEnd":584,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/a2a/LegacyA2aOperationService.java#L560-L584","documentation":"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.","triggerScenarios":"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.","commonSituations":"Namespace mismatch. Agent was deleted by another process. Typo in agent name. Cross-environment confusion. Stale reference to an agent that was cleaned up.","solutions":["List agents in the target namespace to confirm the name exists before operating on it.","Verify the namespaceId matches where the agent was created.","If the agent was deleted, create it first via releaseAgent/registerAgent.","Check for typos or encoding issues in the agent name (names are encoded via agentIdCodecHolder)."],"exampleFix":"// before\nvar card = a2aService.getAgentCard(ns, \"my-agnet\", version, \"\"); // typo\n\n// after\nvar agents = a2aService.listAgents(ns, \"my-agen\", ...);\nString exactName = agents.stream()\n    .map(AgentSummary::getName)\n    .filter(n -> n.startsWith(\"my-agen\"))\n    .findFirst()\n    .orElseThrow();\nvar card = a2aService.getAgentCard(ns, exactName, version, \"\");","handlingStrategy":"validation","validationCode":"// Verify the agent exists before operating on it\ntry {\n    a2aService.getAgentCard(ns, agentName, StringUtils.EMPTY, StringUtils.EMPTY);\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.AGENT_NOT_FOUND.getCode()) {\n        // agent does not exist — create first or surface error\n        throw new IllegalStateException(\"Agent not found, create it first: \" + agentName);\n    }\n}","typeGuard":"public static boolean agentExists(\n        A2aOperationService svc, String ns, String name) {\n    try {\n        svc.getAgentCard(ns, name, StringUtils.EMPTY, StringUtils.EMPTY);\n        return true;\n    } catch (NacosApiException e) {\n        return e.getDetailErrCode() != ErrorCode.AGENT_NOT_FOUND.getCode();\n    }\n}","tryCatchPattern":"try {\n    a2aService.getAgentCard(ns, agentName, version, \"\");\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.AGENT_NOT_FOUND.getCode()) {\n        // agent missing — create it first, then retry\n        a2aService.releaseAgent(agentCard, ns, registrationType, true);\n        a2aService.getAgentCard(ns, agentName, version, \"\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Confirm the agent name and namespaceId are correct before operations.","List agents first to verify the name exists.","Watch for encoding issues in agent names (they are encoded via agentIdCodecHolder)."],"tags":["a2a","agent","not-found","namespace","config-query"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}