alibaba/nacos · critical · NacosLoadException

serverList is empty,please check configuration

Error message

serverList is empty,please check configuration

What it means

Thrown by NamingServerListManager.start() (as NacosLoadException, a NacosException subclass) when the resolved server address list is empty. The naming client cannot operate without at least one server endpoint. This is a configuration/startup failure: the properties passed to the NamingService did not yield any server address (neither serverAddr nor a discovery mechanism returned hosts).

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/naming/core/NamingServerListManager.java:64

    private String nacosDomain;
    
    private boolean isDomain;
    
    @JustForTest
    public NamingServerListManager(Properties properties) {
        this(NacosClientProperties.PROTOTYPE.derive(properties), "");
    }
    
    public NamingServerListManager(NacosClientProperties properties, String namespace) {
        super(properties, namespace);
    }
    
    @Override
    public void start() throws NacosException {
        super.start();
        List<String> serverList = getServerList();
        if (serverList.isEmpty()) {
            throw new NacosLoadException("serverList is empty,please check configuration");
        } else {
            currentIndex.set(ThreadLocalRandom.current().nextInt(serverList.size()));
        }
        if (serverListProvider instanceof PropertiesListProvider) {
            if (serverList.size() == 1) {
                isDomain = true;
                nacosDomain = serverList.get(0);
            }
        }
    }
    
    public String getNacosDomain() {
        return nacosDomain;
    }
    
    public boolean isDomain() {
        return isDomain;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set PropertyKeyConst.SERVER_ADDR (e.g. properties.put("serverAddr", "host:port")) before constructing the NamingService/NacosLockService.
2. Verify the property name and value are correct and non-empty; log the properties (excluding secrets) at startup.
3. If using endpoint/discovery-based addressing, confirm the endpoint returns at least one address.
4. Fail fast at application startup with a clear message if no server is configured.

Example fix

// before
Properties props = new Properties();
NamingService naming = NamingFactory.createNamingService(props); // throws NacosLoadException

// after
Properties props = new Properties();
props.put(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
NamingService naming = NamingFactory.createNamingService(props);

String serverAddr = properties.getProperty(PropertyKeyConst.SERVER_ADDR);
if (serverAddr == null || serverAddr.trim().isEmpty()) {
    throw new IllegalArgumentException("serverAddr must be configured for NamingService");
}

When it happens

Trigger: Constructing a NamingService/NacosLockService without a serverAddr property (or with an empty/blank value); the address source (properties, endpoint, DNS) resolved to zero addresses; a typo in the property key for the server list.

Common situations: Missing PropertyKeyConst.SERVER_ADDR in the Properties; empty value for serverAddr; endpoint/discovery-based addressing returning nothing; misconfigured environment-specific properties; container missing the config injection.

Related errors

• 400
• 400
• [http-client] invalid connect timeout:{}
• 500
• Param 'resourcePattern' is illegal, resourcePattern is blank

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