alibaba/spring-ai-alibaba · error · NacosRuntimeException

NacosRuntimeException(e.getErrCode(), e.getErrMsg())

Error message

NacosRuntimeException(e.getErrCode(), e.getErrMsg())

What it means

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.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/registry/nacos/discovery/NacosAgentCardProvider.java:77

	@Override
	public AgentCardWrapper getAgentCard(String agentName) {
		try {
			AgentCard nacosAgentCard = a2aService.getAgentCard(agentName);
			agentCard = new NacosAgentCardWrapper(AgentCardConverterUtil.convertToA2aAgentCard(nacosAgentCard));
			a2aService.subscribeAgentCard(agentName, new AbstractNacosAgentCardListener() {
				@Override
				public void onEvent(NacosAgentCardEvent event) {
					AgentCard newAgentCard = event.getAgentCard();
					if (LOGGER.isDebugEnabled()) {
						LOGGER.debug("Received new Agent Card: {}", JacksonUtils.toJson(newAgentCard));
					}
					agentCard.setAgentCard(AgentCardConverterUtil.convertToA2aAgentCard(newAgentCard));
				}
			});
			return agentCard;
		}
		catch (NacosException e) {
			throw new NacosRuntimeException(e.getErrCode(), e.getErrMsg());
		}
	}

	@Override
	public boolean supportGetAgentCardByName() {
		return true;
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the wrapped errCode/errMsg and Nacos server logs to identify the root cause (connection refused vs. not found vs. auth).
2. Verify Nacos configuration: server-addr, namespace, group, and credentials in your Spring configuration.
3. Confirm the target agent is registered in Nacos (check the A2A service list in the Nacos console) and retry after registration completes.
4. Catch NacosRuntimeException around getAgentCard and implement retry-with-backoff for transient network issues.
5. Test Nacos connectivity from the app host (e.g., curl http://<nacos>:8848/nacos) to rule out firewall/VPN issues.

// before calling: verify Nacos reachability
// HttpURLConnection ping to http://<nacos-server>/nacos/v1/console/health/readiness

try {
    return provider.getAgentCard(agentName);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == ...connect/refused...) { retryWithBackoff(); }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Register agent card to Nacos failed (rethrown as NacosRuntim
• Please use getAgentCard(agentName) first.
• No available endpoint found for service: <serviceName>
• Failed to subscribe
• Oauth2CallError

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/5b4a443cc84fde16. Report an issue: GitHub.