quarkusio/quarkus · critical · ConfigurationException

Redis host not configured - you must either configure 'quark

Error message

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.

What it means

VertxRedisClientFactory.create() builds the Redis client from Quarkus configuration. If neither `quarkus.redis.hosts` is set nor `quarkus.redis.host-provider-name` points to a bean providing hosts programmatically, the hosts collection is empty and no connection target exists, so a ConfigurationException is thrown. This is a fail-fast guard so startup fails instead of producing a client that cannot connect.

Source

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

                        options.addConnectionString(newURI);
                    } else {
                        options.addConnectionString(uri.toString().trim());
                    }
                }
            }
        };

        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));

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.redis.hosts=redis://localhost:6379 (or your Redis URI) in application.properties.
If hosts must be computed at runtime, define a RedisHostsProvider bean and set quarkus.redis.host-provider-name to its @Identifier value.
Check that the active Quarkus profile includes the redis hosts property (e.g. %prod.quarkus.redis.hosts).

Example fix

// before (application.properties)
# quarkus.redis.hosts not set

// after
quarkus.redis.hosts=redis://localhost:6379

Defensive patterns

Strategy: validation

Validate before calling

if (!ConfigUtils.isPropertyPresent("quarkus.redis.hosts") && !ConfigUtils.isPropertyPresent("quarkus.redis.host-provider-name")) {
    throw new IllegalStateException("Configure quarkus.redis.hosts or quarkus.redis.host-provider-name before using the Redis client");
}

Prevention

Always set quarkus.redis.hosts when adding the redis-client extension.
Use SmallRye Config mapping tests (e.g. @TestProfile) to verify Redis config for every profile.
Document required Redis properties per environment (dev/test/prod).

When it happens

Trigger: At application startup, when create() processes a RedisConfig whose hosts property is absent and hostsProviderName is absent (the final else branch of the hosts resolution).

Common situations: Adding the redis-client extension but never setting quarkus.redis.hosts in application.properties; profiles (test/prod) where hosts is only defined in one profile; relying on a RedisHostsProvider bean but forgetting to set host-provider-name or forgetting @Identifier on the bean.

Related errors

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