alibaba/Sentinel · error · IllegalStateException

Nacos config service has not been initialized or error occur

Error message

Nacos config service has not been initialized or error occurred

What it means

Thrown by NacosDataSource.readSource() when the internal Nacos ConfigService is null. Construction swallows exceptions from NacosFactory.createConfigService (it only logs via RecordLog.warn and printStackTrace), so a bad address/credentials leave configService null; every later read (initial load and timer refresh) then hits this IllegalStateException.

Source

Thrown at sentinel-extension/sentinel-datasource-nacos/src/main/java/com/alibaba/csp/sentinel/datasource/nacos/NacosDataSource.java:139

            RecordLog.warn("[NacosDataSource] Error when loading initial config", ex);
        }
    }

    private void initNacosListener() {
        try {
            this.configService = NacosFactory.createConfigService(this.properties);
            // Add config listener.
            configService.addListener(dataId, groupId, configListener);
        } catch (Exception e) {
            RecordLog.warn("[NacosDataSource] Error occurred when initializing Nacos data source", e);
            e.printStackTrace();
        }
    }

    @Override
    public String readSource() throws Exception {
        if (configService == null) {
            throw new IllegalStateException("Nacos config service has not been initialized or error occurred");
        }
        return configService.getConfig(dataId, groupId, DEFAULT_TIMEOUT);
    }

    @Override
    public void close() {
        if (configService != null) {
            configService.removeListener(dataId, groupId, configListener);
            try {
                configService.shutDown();
            } catch (Exception e) {
                RecordLog.warn("[NacosDataSource] Error occurred when closing Nacos data source", e);
                e.printStackTrace();
            }
        }
        pool.shutdownNow();
    }

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Check the startup logs for '[NacosDataSource] Error occurred when initializing Nacos data source' — the swallowed cause (connect refused, auth failure, etc.) is printed there and tells you the real problem.
2. Fix the connection properties: correct serverAddr host:port, valid namespace/username/password, reachable network route.
3. Ensure the Nacos server is up before the app starts, or add startup ordering/health checks; once properties are fixed, restart the application (the client is not retried).
4. Prefer constructing ConfigService yourself and verifying connectivity before creating the data source, so failures surface at boot instead of on every read.

Example fix

// before
new NacosDataSource<>(props, groupId, dataId, parser); // fails silently, readSource() throws later

// after
ConfigService cs = NacosFactory.createConfigService(props); // throws at boot if unreachable
cs.getConfig(dataId, groupId, 3000); // fail fast on connectivity
new NacosDataSource<>(props, groupId, dataId, parser);

// pre-verify connectivity before creating the data source
ConfigService cs = NacosFactory.createConfigService(props);
String probe = cs.getConfig(dataId, groupId, 3000); // throws with a real cause if unreachable
new NacosDataSource<>(props, groupId, dataId, parser);

// wrap reads from the data source
try {
    T cfg = dataSource.loadConfig();
} catch (Exception e) {
    Throwable cause = (e.getCause() != null) ? e.getCause() : e;
    if (cause instanceof IllegalStateException && cause.getMessage().contains("not been initialized")) {
        log.error("Nacos client failed to init; check serverAddr/credentials in properties and restart", cause);
    }
    throw e;
}

When it happens

Trigger: Nacos server address wrong/unreachable at startup, missing required properties (serverAddr), bad credentials, or a Nacos client version conflict causing createConfigService to throw — the exception is logged and swallowed, then loadConfig()/readSource() throws this error.

Common situations: Typo in serverAddr (e.g. wrong port); Nacos not up yet when the app starts (race); namespace/credential properties misconfigured; mixing incompatible nacos-client versions on the classpath. The app appears to start, then repeatedly logs this exception from the refresh thread while rules never load.

Related errors

• Redis client or Redis Cluster client has not been initialize
• Zookeeper has not been initialized or error occurred
• Bad argument: groupId=[%s], dataId=[%s]
• Consul has not been initialized or error occurred
• File can't be null or a directory

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/fb8b4c0f3f16109b. Report an issue: GitHub.