quarkusio/quarkus · error · ConfigurationException

Multiple Redis hosts supplied for non-clustered configuratio

Error message

Multiple Redis hosts supplied for non-clustered configuration

What it means

When the Redis client type is STANDALONE, VertxRedisClientFactory.create() enforces that at most one host is supplied. A standalone (non-cluster, non-sentinel) Redis client connects to a single endpoint, so multiple hosts are a configuration contradiction and startup fails with a ConfigurationException.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/runtime/client/VertxRedisClientFactory.java:92

        };

        List<URI> hosts = new ArrayList<>();
        if (config.hosts().isPresent()) {
            hosts.addAll(config.hosts().get());
            configureOptions.accept(config.hosts().get());
        } else if (config.hostsProviderName().isPresent()) {
            RedisHostsProvider hostsProvider = findProvider(config.hostsProviderName().get());
            Collection<URI> computedHosts = hostsProvider.getHosts();
            hosts.addAll(computedHosts);
            configureOptions.accept(computedHosts);
        } else {
            throw new ConfigurationException("Redis host not configured - you must either configure 'quarkus.redis.hosts` or" +
                    " 'quarkus.redis.host-provider-name' and have a bean providing the hosts programmatically.");
        }

        if (RedisClientType.STANDALONE == config.clientType()) {
            if (hosts.size() > 1) {
                throw new ConfigurationException("Multiple Redis hosts supplied for non-clustered configuration");
            }
        }

        config.masterName().ifPresent(options::setMasterName);
        options.setMaxNestedArrays(config.maxNestedArrays());
        options.setMaxPoolSize(config.maxPoolSize());
        options.setMaxPoolWaiting(config.maxPoolWaiting());
        options.setMaxWaitingHandlers(config.maxWaitingHandlers());

        options.setProtocolNegotiation(config.protocolNegotiation());
        config.preferredProtocolVersion().ifPresent(options::setPreferredProtocolVersion);
        options.setPassword(config.password().orElse(null));
        config.poolCleanerInterval().ifPresent(d -> options.setPoolCleanerInterval((int) d.toMillis()));
        config.poolRecycleTimeout().ifPresent(d -> options.setPoolRecycleTimeout((int) d.toMillis()));
        config.topologyCacheTtl().ifPresent(d -> options.setTopologyCacheTTL((int) d.toMillis()));

        config.role().ifPresent(options::setRole);
        options.setType(config.clientType());

View on GitHub (pinned to e1c734241f)

Solutions

1. Supply exactly one host in quarkus.redis.hosts for a standalone client.
2. If you really connect to a Redis cluster, set quarkus.redis.client-type=cluster.
3. If using Redis Sentinel, set quarkus.redis.client-type=sentinel and configure quarkus.redis.master-name.

Example fix

// before
quarkus.redis.hosts=redis://host1:6379,redis://host2:6379

// after (cluster)
quarkus.redis.client-type=cluster
quarkus.redis.hosts=redis://host1:6379,redis://host2:6379

String hosts = config.getValue("quarkus.redis.hosts", String.class);
String type = config.getOptionalValue("quarkus.redis.client-type", String.class).orElse("standalone");
if ("standalone".equalsIgnoreCase(type) && hosts.split(",").length > 1) {
    throw new IllegalStateException("Standalone Redis client accepts exactly one host");
}

When it happens

Trigger: At startup, after host resolution, when config.clientType() == RedisClientType.STANDALONE and the resolved hosts collection contains more than one URI (e.g. quarkus.redis.hosts=redis://h1:6379,redis://h2:6379).

Common situations: Copy-pasting a cluster-style comma-separated host list while leaving the default STANDALONE client type; defining hosts via a host provider that returns several URIs for a standalone setup.

Related errors

• Redis host not configured - you must either configure 'quark
• Unable to find redis host provider identified with " + name
• Unable to find redis host provider
• Unable to find the TLS configuration " + config.tlsConfigura
• Failed to load application configuration

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/44359b538396e622. Report an issue: GitHub.