{"record":{"id":"fbab20901c0579ab","repo":"alibaba/nacos","slug":"500-fbab20","errorCode":"500","errorMessage":"fail to get NACOS-server serverlist! not connnect url:{}","messagePattern":"fail to get NACOS-server serverlist! not connnect url:(.+?)","errorType":"exception","errorClass":"NacosException","httpStatus":500,"severity":"critical","filePath":"client-basic/src/main/java/com/alibaba/nacos/client/address/EndpointServerListProvider.java","lineNumber":165,"sourceCode":"     * @throws NacosException nacos exception\n     */\n    public void startRefreshServerListTask(NacosClientProperties properties) throws NacosException {\n        for (int i = 0; i < initServerListRetryTimes && getServerList().isEmpty(); ++i) {\n            refreshServerListIfNeed();\n            if (!serversFromEndpoint.isEmpty()) {\n                break;\n            }\n            try {\n                this.wait((i + 1) * 100L);\n            } catch (Exception e) {\n                LOGGER.warn(\"get serverlist fail,url: {}\", addressServerUrl);\n            }\n        }\n        \n        if (serversFromEndpoint.isEmpty()) {\n            LOGGER.error(\"[init-serverlist] fail to get NACOS-server serverlist! url: {}\",\n                addressServerUrl);\n            throw new NacosException(NacosException.SERVER_ERROR,\n                \"fail to get NACOS-server serverlist! not connnect url:\" + addressServerUrl);\n        }\n        \n        refreshServerListExecutor = new ScheduledThreadPoolExecutor(1,\n            new NameThreadFactory(\n                \"com.alibaba.nacos.client.address.EndpointServerListProvider.refreshServerList\"));\n        // executor schedules the timer task\n        long refreshInterval = Long.parseLong(\n            properties.getProperty(PropertyKeyConst.ENDPOINT_REFRESH_INTERVAL_SECONDS, \"30\"));\n        refreshServerListExecutor.scheduleWithFixedDelay(this::refreshServerListIfNeed, 0L,\n            refreshInterval,\n            TimeUnit.SECONDS);\n    }\n    \n    private void refreshServerListIfNeed() {\n        try {\n            if (System.currentTimeMillis()\n                - lastServerListRefreshTime < refreshServerListInternal) {","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client-basic/src/main/java/com/alibaba/nacos/client/address/EndpointServerListProvider.java#L147-L183","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before — relying on endpoint that is down\nprops.setProperty(PropertyKeyConst.ENDPOINT, \"addr.nacos.internal:8080\");\n\n// after — provide server list directly\nprops.setProperty(PropertyKeyConst.SERVER_ADDR, \"10.0.0.1:8848,10.0.0.2:8848\");","handlingStrategy":"try-catch","validationCode":"String endpointUrl = buildAddressServerUrl(endpoint, port, contextPath, serverListName);\ntry {\n    HttpRestResult<String> result = restTemplate.get(endpointUrl, Header.EMPTY, Query.EMPTY, String.class);\n    if (!result.ok() || StringUtils.isBlank(result.getData())) {\n        throw new IllegalStateException(\"Address server returned empty list at: \" + endpointUrl);\n    }\n} catch (Exception e) {\n    throw new IllegalStateException(\"Cannot reach address server: \" + endpointUrl, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    namingService = NamingFactory.createNamingService(props);\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR && e.getMessage().contains(\"serverlist\")) {\n        // Fallback: switch to explicit server list\n        props.setProperty(PropertyKeyConst.SERVER_ADDR, \"127.0.0.1:8848\");\n        namingService = NamingFactory.createNamingService(props);\n    } else {\n        throw e;\n    }\n}","preventionTips":["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."],"tags":["network","server-discovery","endpoint","retry-exhausted"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}