{"record":{"id":"06b7d7a1e8bfecde","repo":"alibaba/spring-ai-alibaba","slug":"register-agent-card-to-nacos-failed-rethrown-as-n","errorCode":null,"errorMessage":"Register agent card to Nacos failed (rethrown as NacosRuntimeException(e.getErrCode(), e.getErrMsg()))","messagePattern":"Register agent card to Nacos failed \\(rethrown as 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/service/NacosA2aOperationService.java","lineNumber":66,"sourceCode":"\tprivate final NacosA2aRegistryProperties nacosA2aRegistryProperties;\n\n\tpublic NacosA2aOperationService(A2aService a2aService, NacosA2aProperties nacosA2aProperties,\n\t\t\tA2aServerProperties a2aServerProperties, NacosA2aRegistryProperties nacosA2aRegistryProperties) {\n\t\tthis.a2aService = a2aService;\n\t\tthis.nacosA2aProperties = nacosA2aProperties;\n\t\tthis.a2aServerProperties = a2aServerProperties;\n\t\tthis.nacosA2aRegistryProperties = nacosA2aRegistryProperties;\n\t}\n\n\tpublic void registerAgent(io.a2a.spec.AgentCard agentCard) {\n\t\tAgentCard nacosAgentCard = AgentCardConverterUtil.convertToNacosAgentCard(agentCard);\n\t\ttry {\n\t\t\ttryReleaseAgentCard(nacosAgentCard);\n\t\t\tregisterEndpoint(nacosAgentCard);\n\t\t}\n\t\tcatch (NacosException e) {\n\t\t\tLOGGER.error(\"Register agent card {} to Nacos failed,\", agentCard.name(), e);\n\t\t\tthrow new NacosRuntimeException(e.getErrCode(), e.getErrMsg());\n\t\t}\n\t}\n\n\tprivate void tryReleaseAgentCard(AgentCard agentCard) throws NacosException {\n\t\tLOGGER.info(\"Register agent card {} to Nacos namespace {}. \", agentCard.getName(),\n\t\t\t\tnacosA2aProperties.getNamespace());\n\t\ta2aService.releaseAgentCard(agentCard, AiConstants.A2a.A2A_ENDPOINT_TYPE_SERVICE,\n\t\t\t\tnacosA2aRegistryProperties.isRegisterAsLatest());\n\t\tLOGGER.info(\"Register agent card {} to Nacos namespace {} successfully. \", agentCard.getName(),\n\t\t\t\tnacosA2aProperties.getNamespace());\n\t}\n\n\tprivate void registerEndpoint(AgentCard agentCard) throws NacosException {\n\t\tAgentEndpoint endpoint = new AgentEndpoint();\n\t\tendpoint.setVersion(agentCard.getVersion());\n\t\tendpoint.setPath(a2aServerProperties.getMessageUrl());\n\t\tendpoint.setTransport(agentCard.getPreferredTransport());\n\t\tendpoint.setAddress(a2aServerProperties.getAddress());","sourceCodeStart":48,"sourceCodeEnd":84,"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/service/NacosA2aOperationService.java#L48-L84","documentation":"NacosA2aOperationService.registerAgent() publishes an A2A AgentCard to a Nacos registry. Before registering it first tries to release any previously registered card (tryReleaseAgentCard) and then registers the endpoint. If either operation throws a NacosException (client/registry communication failure, invalid namespace, naming service error), the exception is logged and rethrown as a NacosRuntimeException carrying the Nacos errCode and errMsg.","triggerScenarios":"Calling registerAgent(agentCard) when the Nacos server is unreachable, the configured namespace does not exist or is wrong, credentials/properties (NacosA2aProperties) are invalid, or tryReleaseAgentCard/registerEndpoint fails at the Nacos client level with a NacosException.","commonSituations":"Nacos server down or wrong server address in spring.cloud.nacos config; namespace configured in nacosA2aProperties does not exist on the server; auth failure (missing username/password/accessToken); network partition or firewall blocking the Nacos port; Nacos client version mismatch with server.","solutions":["Verify the Nacos server address and that the server is reachable (curl the Nacos console).","Check that the namespace configured via NacosA2aProperties exists in Nacos; create it if missing.","Verify Nacos credentials/ACL settings if the server has authentication enabled.","Inspect the wrapped NacosRuntimeException errCode to identify the specific Nacos failure (e.g. 400 invalid param, 403 auth, 503 server).","Retry registration once the network/registry issue is resolved; consider retry with backoff for transient outages."],"exampleFix":"// before\nNacosA2aOperationService service = new NacosA2aOperationService(namingService, props);\nservice.registerAgent(agentCard); // throws NacosRuntimeException on any NacosException\n// after\ntry {\n    service.registerAgent(agentCard);\n} catch (NacosRuntimeException e) {\n    LOGGER.error(\"Agent card registration failed, errCode={} msg={}\", e.getErrCode(), e.getMessage(), e);\n    // check Nacos server/namespace/credentials before retrying\n}","handlingStrategy":"try-catch","validationCode":"// Java: pre-check before registerAgent\nboolean reachable = false;\ntry {\n    reachable = new Socket(nacosHost, nacosPort).isConnected();\n} catch (IOException ignored) {}\nif (!reachable) throw new IllegalStateException(\"Nacos server unreachable at \" + nacosHost + \":\" + nacosPort);\nif (nacosA2aProperties.getNamespace() == null || nacosA2aProperties.getNamespace().isBlank())\n    throw new IllegalStateException(\"Nacos namespace must be configured\");","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n    nacosA2aOperationService.registerAgent(agentCard);\n} catch (NacosRuntimeException e) {\n    LOGGER.error(\"Nacos registration failed errCode={} msg={}\", e.getErrCode(), e.getMessage(), e);\n    // alert / schedule retry after connectivity check\n}","preventionTips":["Health-check the Nacos server at startup before registering agent cards.","Create the target namespace in Nacos in advance and keep it in sync with configuration.","Enable Nacos client logging to surface auth/network errors early.","Retry registration with exponential backoff for transient network failures."],"tags":["nacos","a2a","registry","network","service-discovery"],"backgroundTag":"http-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"}