alibaba/nacos · critical · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

no server available

What it means

Thrown by AiHttpClientProxy.requestAgentApi when the server list managed by serverListManager is empty. Before attempting any agent HTTP call the client needs at least one target server; an empty list is treated as INVALID_PARAM (misconfiguration) rather than a network error. This path serves agent discovery/registry REST calls.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/remote/AiHttpClientProxy.java:449

    
    private void putJson(Map<String, String> form, String name, Object value) {
        if (value != null) {
            form.put(name, JsonUtils.toJson(value));
        }
    }
    
    private RequestResource buildAgentResource(String agentName) {
        return RequestResource.aiBuilder().setNamespace(namespaceId)
            .setGroup(Constants.DEFAULT_GROUP)
            .setResource(agentName == null ? StringUtils.EMPTY : agentName).build();
    }
    
    private String requestAgentApi(String api, AgentHttpMethod method,
        List<QueryParameter> parameters, Map<String, String> form, RequestResource resource)
        throws NacosException {
        List<String> servers = serverListManager.getServerList();
        if (servers.isEmpty()) {
            throw new NacosException(NacosException.INVALID_PARAM, "no server available");
        }
        NacosException exception = new NacosException();
        int index = ThreadLocalRandom.current().nextInt(servers.size());
        for (int i = 0; i < Math.max(servers.size(), MAX_RETRY); i++) {
            String server = servers.get(index % servers.size());
            try {
                return callAgentServer(api, method, parameters, form, server, resource);
            } catch (NacosException e) {
                exception = e;
            }
            index = (index + 1) % servers.size();
        }
        throw new NacosException(exception.getErrCode(),
            "Failed to request API: " + api + " after all servers(" + servers + ") tried: "
                + exception.getMessage());
    }
    
    private String callAgentServer(String api, AgentHttpMethod method,

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Provide a valid, non-empty serverAddr when building the AI client (e.g. Properties.SERVER_ADDRESSES).
  2. Verify the server list endpoint (if using a discovery endpoint) returns at least one healthy server.
  3. Check the server list property spelling/format; ensure it parses into addresses.

Example fix

// before
Properties props = new Properties();
// serverAddr omitted
NacosAiService service = NacosAiServiceBuilder.build(props); // later: no server available
// after
props.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
NacosAiService service = NacosAiServiceBuilder.build(props);
Defensive patterns

Strategy: validation

Validate before calling

if (serverListManager.getServerList().isEmpty()) {
    throw new IllegalStateException("No Nacos servers configured; set serverAddr");
}

Type guard

!serverListManager.getServerList().isEmpty()

Try / catch

try {
    client.requestAgentApi(...);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM && "no server available".equals(e.getMessage())) {
        // fix serverAddr / server-list configuration
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling an agent API (requestAgentApi, used by discovery/registry HTTP operations) when serverListManager.getServerList() returns an empty list - server list never populated, or all servers removed.

Common situations: Server address property (serverAddr) not set or empty; server list fetch from the endpoint failed and yielded nothing; client initialized with a blank server list; fixed server list property malformed.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/ec551a7313c3aba3. Report an issue: GitHub.