alibaba/Sentinel · error · IllegalStateException

Redis client or Redis Cluster client has not been initialize

Error message

Redis client or Redis Cluster client has not been initialized or error occurred

What it means

Thrown by RedisDataSource.readSource() when both the RedisClient and RedisClusterClient are null. As with Nacos, initialization errors are caught and only logged, so a failed Lettuce client construction leaves the fields null and each subsequent read (initial load + refresh) throws this IllegalStateException.

Source

Thrown at sentinel-extension/sentinel-datasource-redis/src/main/java/com/alibaba/csp/sentinel/datasource/redis/RedisDataSource.java:261

        }
    }

    private void loadInitialConfig() {
        try {
            T newValue = loadConfig();
            if (newValue == null) {
                RecordLog.warn("[RedisDataSource] WARN: initial config is null, you may have to check your data source");
            }
            getProperty().updateValue(newValue);
        } catch (Exception ex) {
            RecordLog.warn("[RedisDataSource] Error when loading initial config", ex);
        }
    }

    @Override
    public String readSource() {
        if (this.redisClient == null && this.redisClusterClient == null) {
            throw new IllegalStateException("Redis client or Redis Cluster client has not been initialized or error occurred");
        }

        if (redisClient != null) {
            RedisCommands<String, String> stringRedisCommands = redisClient.connect().sync();
            return stringRedisCommands.get(ruleKey);
        } else {
            RedisAdvancedClusterCommands<String, String> stringRedisCommands = redisClusterClient.connect().sync();
            return stringRedisCommands.get(ruleKey);
        }
    }

    @Override
    public void close() {
        if (redisClient != null) {
            redisClient.shutdown();
        } else {
            redisClusterClient.shutdown();
        }

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Inspect startup logs for '[RedisDataSource] Error occurred when initializing' or '[RedisDataSource] WARN: initial config is null' — the swallowed cause identifies the connection problem.
2. Verify Redis reachability and credentials from the same host: redis-cli -h <host> -p <port> -a <password> PING.
3. Fix RedisConnectionConfig (host/port for standalone, nodes for cluster/sentinel) and restart the application.
4. Test the Lettuce connection yourself before constructing the data source so a failure aborts startup with a clear error.

Example fix

// before
RedisConnectionConfig cfg = RedisConnectionConfig.builder().withHost("wrong-host").build();
new RedisDataSource<>(cfg, ruleKey, parser);

// after
RedisConnectionConfig cfg = RedisConnectionConfig.builder().withHost("redis.prod").withPort(6379).build();
RedisClient client = RedisClient.create(cfg);           // fails fast if config is unusable
client.connect().sync().ping();                          // verify connectivity
new RedisDataSource<>(cfg, ruleKey, parser);

// pre-verify the connection before creating the data source
RedisClient probe = RedisClient.create(cfg);
probe.connect().sync().ping();  // throws with a real cause if unreachable/bad auth
probe.shutdown();
new RedisDataSource<>(cfg, ruleKey, parser);

try {
    String raw = dataSource.loadConfig();
} catch (Exception e) {
    if (e instanceof IllegalStateException && e.getMessage().contains("not been initialized")) {
        log.error("Lettuce client failed to init; check Redis host/port/password and restart", e);
    }
    throw e;
}

When it happens

Trigger: Constructing RedisDataSource with a RedisConnectionConfig that Lettuce cannot use (bad host/port, unreachable Redis, auth failure), so RedisClient.create(...) throws inside the constructor; readSource() then finds both clients null.

Common situations: Wrong Redis host/port/password in the connection config; Redis behind a firewall or not started; using the single-node constructor against a cluster endpoint (or vice versa) so connect() fails. App starts but logs this exception from the rule-refresh thread and never loads rules.

Related errors

• Nacos config service has not been initialized or error occur
• Zookeeper has not been initialized or error occurred
• Consul has not been initialized or error occurred
• File can't be null or a directory
• charset can't be null

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