{"record":{"id":"5b4a443cc84fde16","repo":"alibaba/spring-ai-alibaba","slug":"nacosruntimeexception-e-geterrcode-e-geterrmsg","errorCode":null,"errorMessage":"NacosRuntimeException(e.getErrCode(), e.getErrMsg())","messagePattern":"NacosRuntimeException\\(e\\.getErrCode\\(\\), e\\.getErrMsg\\(\\)\\)","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/registry/nacos/discovery/NacosAgentCardProvider.java","lineNumber":77,"sourceCode":"\t@Override\n\tpublic AgentCardWrapper getAgentCard(String agentName) {\n\t\ttry {\n\t\t\tAgentCard nacosAgentCard = a2aService.getAgentCard(agentName);\n\t\t\tagentCard = new NacosAgentCardWrapper(AgentCardConverterUtil.convertToA2aAgentCard(nacosAgentCard));\n\t\t\ta2aService.subscribeAgentCard(agentName, new AbstractNacosAgentCardListener() {\n\t\t\t\t@Override\n\t\t\t\tpublic void onEvent(NacosAgentCardEvent event) {\n\t\t\t\t\tAgentCard newAgentCard = event.getAgentCard();\n\t\t\t\t\tif (LOGGER.isDebugEnabled()) {\n\t\t\t\t\t\tLOGGER.debug(\"Received new Agent Card: {}\", JacksonUtils.toJson(newAgentCard));\n\t\t\t\t\t}\n\t\t\t\t\tagentCard.setAgentCard(AgentCardConverterUtil.convertToA2aAgentCard(newAgentCard));\n\t\t\t\t}\n\t\t\t});\n\t\t\treturn agentCard;\n\t\t}\n\t\tcatch (NacosException e) {\n\t\t\tthrow new NacosRuntimeException(e.getErrCode(), e.getErrMsg());\n\t\t}\n\t}\n\n\t@Override\n\tpublic boolean supportGetAgentCardByName() {\n\t\treturn true;\n\t}\n\n}\n","sourceCodeStart":59,"sourceCodeEnd":87,"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/registry/nacos/discovery/NacosAgentCardProvider.java#L59-L87","documentation":"NacosAgentCardProvider.getAgentCard(String) fetches the agent card via the Nacos client; if the underlying call throws a checked NacosException, the provider rethrows it as an unchecked NacosRuntimeException carrying the Nacos errCode and errMsg. This converts registry/client failures (connection problems, service not found, config errors) into a runtime exception callers can catch without Nacos's checked-exception API leaking.","triggerScenarios":"Calling getAgentCard(agentName) when the Nacos server call fails: Nacos server unreachable, the named agent/service is not registered, timeout, authentication failure with Nacos, or an invalid namespace/cluster — any of which surfaces as NacosException internally.","commonSituations":"Wrong Nacos server address or port in configuration; Nacos down or network partition; agent not yet registered (startup ordering) so lookup fails; wrong namespace/group so the service isn't visible; Nacos auth credentials missing/expired.","solutions":["Check the wrapped errCode/errMsg and Nacos server logs to identify the root cause (connection refused vs. not found vs. auth).","Verify Nacos configuration: server-addr, namespace, group, and credentials in your Spring configuration.","Confirm the target agent is registered in Nacos (check the A2A service list in the Nacos console) and retry after registration completes.","Catch NacosRuntimeException around getAgentCard and implement retry-with-backoff for transient network issues.","Test Nacos connectivity from the app host (e.g., curl http://<nacos>:8848/nacos) to rule out firewall/VPN issues."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// before calling: verify Nacos reachability\n// HttpURLConnection ping to http://<nacos-server>/nacos/v1/console/health/readiness","typeGuard":null,"tryCatchPattern":"try {\n    return provider.getAgentCard(agentName);\n} catch (NacosRuntimeException e) {\n    if (e.getErrCode() == ...connect/refused...) { retryWithBackoff(); }\n    throw e;\n}","preventionTips":["Validate Nacos server-addr, namespace, group and credentials at startup","Retry lookups with backoff during agent registration windows","Health-check Nacos connectivity before dependent lookups","Log e.getErrCode()/errMsg for diagnosis instead of swallowing"],"tags":["nacos","network","service-discovery","registry"],"backgroundTag":"network-request-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}