alibaba/nacos · critical · NacosException

500

500

Error message

fail to get NACOS-server serverlist! not connnect url:{}

What it means

Thrown by EndpointServerListProvider.startRefreshServerListTask() with error code SERVER_ERROR (500) after the server list remains empty through 5 retry attempts (initServerListRetryTimes). The provider tries to fetch the server list from the Nacos address server endpoint URL (addressServerUrl) and, if all attempts return an empty list, throws this exception. The message includes the constructed endpoint URL for diagnosis.

Source

Thrown at client-basic/src/main/java/com/alibaba/nacos/client/address/EndpointServerListProvider.java:165

     * @throws NacosException nacos exception
     */
    public void startRefreshServerListTask(NacosClientProperties properties) throws NacosException {
        for (int i = 0; i < initServerListRetryTimes && getServerList().isEmpty(); ++i) {
            refreshServerListIfNeed();
            if (!serversFromEndpoint.isEmpty()) {
                break;
            }
            try {
                this.wait((i + 1) * 100L);
            } catch (Exception e) {
                LOGGER.warn("get serverlist fail,url: {}", addressServerUrl);
            }
        }
        
        if (serversFromEndpoint.isEmpty()) {
            LOGGER.error("[init-serverlist] fail to get NACOS-server serverlist! url: {}",
                addressServerUrl);
            throw new NacosException(NacosException.SERVER_ERROR,
                "fail to get NACOS-server serverlist! not connnect url:" + addressServerUrl);
        }
        
        refreshServerListExecutor = new ScheduledThreadPoolExecutor(1,
            new NameThreadFactory(
                "com.alibaba.nacos.client.address.EndpointServerListProvider.refreshServerList"));
        // executor schedules the timer task
        long refreshInterval = Long.parseLong(
            properties.getProperty(PropertyKeyConst.ENDPOINT_REFRESH_INTERVAL_SECONDS, "30"));
        refreshServerListExecutor.scheduleWithFixedDelay(this::refreshServerListIfNeed, 0L,
            refreshInterval,
            TimeUnit.SECONDS);
    }
    
    private void refreshServerListIfNeed() {
        try {
            if (System.currentTimeMillis()
                - lastServerListRefreshTime < refreshServerListInternal) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Verify the endpoint URL from the exception message is reachable: curl the addressServerUrl directly.
Check that PropertyKeyConst.ENDPOINT and endpoint port (default 8080) are correct.
If the address server is behind a proxy, ensure the proxy routes correctly and the endpoint returns a non-empty newline-separated server list.
If the address server is not used, switch to PropertyKeyConst.SERVER_ADDR to provide the server list directly instead of an endpoint.

Example fix

// before — relying on endpoint that is down
props.setProperty(PropertyKeyConst.ENDPOINT, "addr.nacos.internal:8080");

// after — provide server list directly
props.setProperty(PropertyKeyConst.SERVER_ADDR, "10.0.0.1:8848,10.0.0.2:8848");

Defensive patterns

Strategy: try-catch

Validate before calling

String endpointUrl = buildAddressServerUrl(endpoint, port, contextPath, serverListName);
try {
    HttpRestResult<String> result = restTemplate.get(endpointUrl, Header.EMPTY, Query.EMPTY, String.class);
    if (!result.ok() || StringUtils.isBlank(result.getData())) {
        throw new IllegalStateException("Address server returned empty list at: " + endpointUrl);
    }
} catch (Exception e) {
    throw new IllegalStateException("Cannot reach address server: " + endpointUrl, e);
}

Try / catch

try {
    namingService = NamingFactory.createNamingService(props);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR && e.getMessage().contains("serverlist")) {
        // Fallback: switch to explicit server list
        props.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
        namingService = NamingFactory.createNamingService(props);
    } else {
        throw e;
    }
}

Prevention

Use SERVER_ADDR instead of ENDPOINT when the address server is unreliable.
Monitor the address server endpoint health separately from the Nacos client.
In production, prefer direct server lists over endpoint discovery for fewer moving parts.

When it happens

Trigger: The address server (endpoint) is unreachable, returns an empty body, returns non-parseable content, or the endpoint URL is misconfigured. The retry loop uses this.wait() which requires the calling thread to hold the object's monitor. Each retry waits (i+1)*100ms.

Common situations: Endpoint host/port is wrong (PropertyKeyConst.ENDPOINT points to a non-existent address server); firewall or network policy blocks access to the address server; the address server is running but returns an empty node list; the context path or server list name property is wrong so the endpoint returns 404/empty.

Related errors

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