alibaba/Sentinel · error · IllegalStateException

Cannot build a RedisConnectionConfig. One of the following m

Error message

Cannot build a RedisConnectionConfig. One of the following must be provided Host, Socket, Cluster or Sentinel

What it means

Thrown by RedisConnectionConfig.Builder.build() when no connection target was configured: the builder has no host, no cluster nodes, and no sentinel nodes. Sentinel's builder (modeled on Spring Data Redis) requires at least one of standalone host, unix socket, cluster, or sentinel addresses before it can produce a config.

Source

Thrown at sentinel-extension/sentinel-datasource-redis/src/main/java/com/alibaba/csp/sentinel/datasource/redis/config/RedisConnectionConfig.java:710

        /**
         * Sets the keyFilePassword.
         *
         * @param keyFilePassword keyFilePassword
         * @return the value of Builder
         */
        public RedisConnectionConfig.Builder withKeyFilePassword(String keyFilePassword) {
            this.keyFilePassword = keyFilePassword;
            return this;
        }

        /**
         * @return the RedisConnectionConfig.
         */
        public RedisConnectionConfig build() {

            if (redisSentinels.isEmpty() && redisClusters.isEmpty() && StringUtil.isEmpty(host)) {
                throw new IllegalStateException(
                    "Cannot build a RedisConnectionConfig. One of the following must be provided Host, Socket, Cluster or "
                        + "Sentinel");
            }

            RedisConnectionConfig redisConnectionConfig = new RedisConnectionConfig();
            redisConnectionConfig.setHost(host);
            redisConnectionConfig.setPort(port);

            if (sslEnable){
                redisConnectionConfig.setSslEnable(true);
                redisConnectionConfig.setTrustedCertificatesPath(trustedCertificatesPath);
                redisConnectionConfig.setTrustedCertificatesJksPassword(trustedCertificatesJksPassword);
                redisConnectionConfig.setKeyCertChainFilePath(keyCertChainFilePath);
                redisConnectionConfig.setKeyFilePath(keyFilePath);
                redisConnectionConfig.setKeyFilePassword(keyFilePassword);
            }

            if (password != null) {

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Add a target: withHost("127.0.0.1") (optionally withPort) for standalone, or withCluster("host:port", ...), or withSentinel("host:port") for sentinel.
2. Validate your config source before building: assert the host/nodes property is non-empty and fail with its name.
3. Build the config once in a factory method with integration-test coverage so a missing host fails CI, not production.

Example fix

// before
RedisConnectionConfig cfg = RedisConnectionConfig.builder()
    .withPort(6379).withPassword("secret").build(); // no host -> throws

// after
RedisConnectionConfig cfg = RedisConnectionConfig.builder()
    .withHost("127.0.0.1").withPort(6379).withPassword("secret").build();

RedisConnectionConfig.Builder b = RedisConnectionConfig.builder();
if (host != null && !host.isEmpty()) { b.withHost(host).withPort(port); }
else if (nodes != null && !nodes.isEmpty()) { for (String n : nodes) b.withCluster(n); }
else { throw new IllegalStateException("redis host or cluster/sentinel nodes must be configured"); }
RedisConnectionConfig cfg = b.build();

try {
    cfg = builder.build();
} catch (IllegalStateException e) {
    throw new IllegalStateException("RedisConnectionConfig incomplete: set host, unix socket, cluster or sentinel nodes", e);
}

When it happens

Trigger: Calling build() after only setting port, password, database, or SSL options — e.g. RedisConnectionConfig.builder().withPort(6379).withPassword(...).build() with no withHost/withSentinel/withCluster/withUnixSocket call.

Common situations: Config properties for the Redis host are optional and unset in one environment; refactoring renames the host property so withHost receives null/empty and the builder silently keeps an empty host; copy-paste builder chains that drop the host line.

Related errors

• File can't be null or a directory
• charset can't be null
• Bad file
• Config encoder cannot be null
• Charset cannot be null

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