{"record":{"id":"2f240da1096e0d6c","repo":"alibaba/spring-ai-alibaba","slug":"agent-not-found-2f240d","errorCode":null,"errorMessage":"Agent not found: {}","messagePattern":"Agent not found: (.+?)","errorType":"http","errorClass":null,"httpStatus":404,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/core/route/MultiAgentJsonRpcRouterProvider.java","lineNumber":94,"sourceCode":"\t\t\t.GET(this.wellKnownUrl, new MultiAgentCardHandler(router))\n\t\t\t.POST(this.messageUrl, new MultiAgentMessageHandler(router))\n\t\t\t.build();\n\t}\n\n\tprivate static class MultiAgentCardHandler implements HandlerFunction<ServerResponse> {\n\n\t\tprivate final MultiAgentRequestRouter router;\n\n\t\tpublic MultiAgentCardHandler(MultiAgentRequestRouter router) {\n\t\t\tthis.router = router;\n\t\t}\n\n\t\t@Override\n\t\tpublic ServerResponse handle(ServerRequest request) throws Exception {\n\t\t\tString agentName = request.pathVariable(\"agentName\");\n\t\t\tJsonRpcA2aRequestHandler handler = router.getHandler(agentName);\n\t\t\tif (handler == null) {\n\t\t\t\tlog.warn(\"Agent not found: {}\", agentName);\n\t\t\t\treturn ServerResponse.status(HttpStatus.NOT_FOUND)\n\t\t\t\t\t.body(\"Agent not found: \" + agentName);\n\t\t\t}\n\t\t\ttry {\n\t\t\t\treturn ServerResponse.ok().body(handler.getAgentCard());\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tlog.error(\"Failed to get Agent Card for {}: {}\", agentName, e.getMessage());\n\t\t\t\treturn ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).build();\n\t\t\t}\n\t\t}\n\n\t}\n\n\tprivate static class MultiAgentMessageHandler implements HandlerFunction<ServerResponse> {\n\n\t\tprivate final MultiAgentRequestRouter router;\n","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/core/route/MultiAgentJsonRpcRouterProvider.java#L76-L112","documentation":"MultiAgentJsonRpcRouterProvider's card handler looks up a JsonRpcA2aRequestHandler for the agentName path variable; when no handler is registered, it returns HTTP 404 with body 'Agent not found: <name>'. This is an intentional 404 response, not a thrown exception.","triggerScenarios":"Requesting the A2A agent card (or RPC route) with an agentName path segment that was never registered in the MultiAgent router.","commonSituations":"Agent registered under a different name than the URL; Nacos registry entry for the agent not yet synced; agent module not loaded at startup; client URL typos or case mismatches in the agent name.","solutions":["Verify the agent name matches a registered handler exactly (check router registration/Nacos registration)","Confirm the agent's handler bean was created and added to the MultiAgent router at startup","List registered agents (via router.getHandler keys or registry UI) and correct the URL","Check Nacos service discovery sync status if agents register remotely"],"exampleFix":"// before\nGET /a2a/agent/ChatBot/card   // 404, registered as \"chatbot\"\n// after\nGET /a2a/agent/chatbot/card","handlingStrategy":"try-catch","validationCode":"boolean registered = router.getHandler(agentName) != null; if (!registered) { /* correct the agent name before calling */ }","typeGuard":null,"tryCatchPattern":"try { ResponseEntity<String> r = rest.getForEntity(cardUrl, String.class); } catch (HttpStatusCodeException e) { if (e.getStatusCode() == HttpStatus.NOT_FOUND) { /* agent not registered - fix name/registration */ } }","preventionTips":["Match agentName in URLs exactly to registered handler names","Confirm agent handler beans/router registrations at startup","Check Nacos registration/sync when agents register via registry"],"tags":["http","not-found","a2a"],"backgroundTag":"resource-not-found","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}