quarkusio/quarkus · error · IllegalArgumentException

Unable import data into Redis - cannot find the Redis client

Error message

Unable import data into Redis - cannot find the Redis client <name>, available clients are: <clients.keySet()>

What it means

The RedisClientRecorder.preload method imports data into a named Redis client at startup, but the requested client name is not present in the map of configured clients. Quarkus throws IllegalArgumentException listing the clients that actually exist so you can spot the name mismatch.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/runtime/client/RedisClientRecorder.java:218

    }

    public void cleanup(ShutdownContext context) {
        context.addShutdownTask(new Runnable() {
            @Override
            public void run() {
                for (RedisClientAndApi value : clients.values()) {
                    value.redis.close();
                }
                clients.clear();
                dataSources.clear();
            }
        });
    }

    public void preload(String name, List<String> loadScriptPaths, boolean redisFlushBeforeLoad, boolean redisLoadOnlyIfEmpty) {
        var tuple = clients.get(name);
        if (tuple == null) {
            throw new IllegalArgumentException("Unable import data into Redis - cannot find the Redis client " + name
                    + ", available clients are: " + clients.keySet());
        }

        if (redisFlushBeforeLoad) {
            tuple.redis.send(Request.cmd(Command.FLUSHALL)).await().indefinitely();
        } else if (redisLoadOnlyIfEmpty) {
            var list = tuple.redis.send(Request.cmd(Command.KEYS).arg("*")).await().indefinitely();
            if (list.size() != 0) {
                RedisDataLoader.LOGGER.debugf(
                        "Skipping the Redis data loading because the database is not empty: %d keys found", list.size());
                return;
            }
        }

        for (String path : loadScriptPaths) {
            RedisDataLoader.load(vertx, tuple.redis, path);
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Align the client name in the preload/import configuration with an existing quarkus.redis.<name> key — the error message lists the valid names
2. If you meant the default client, remove the name qualifier (use quarkus.redis.* config, not quarkus.redis.<name>.*)
3. Check the available clients in the message and correct the typo
4. Define the missing client configuration if it was intentionally expected

Example fix

// before
quarkus.redis.load-script=import.redis
quarkus.redis.cache.load-script=import.redis # 'cache' client not defined
# after
quarkus.redis.load-script=import.redis # use default client
# or define the client:
quarkus.redis.cache.hosts=localhost:6379

Set<String> configured = Map.of("default", true).keySet(); // from your application.properties
String name = "cache";
if (!configured.contains(name)) {
    throw new IllegalArgumentException("Redis client '" + name + "' is not configured; define quarkus.redis." + name + ".*");
}

try {
    recorder.preload(name, scripts, flush, onlyIfEmpty);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Redis preload misconfiguration: " + e.getMessage(), e);
}

When it happens

Trigger: quarkus.redis.load-script or flush/load configuration referencing a client name that does not match any configured client; using the default client configuration while the preload is registered under a named client (or vice versa); renaming quarkus.redis.<name> keys without updating the load config.

Common situations: Dev-services or test data loading configured for a named client that was never defined; typos in quarkus.redis.<name> vs the load-script client reference; multiple Redis clients configured and the wrong one named in the import settings.

Related errors

• Redis host not configured - you must either configure 'quark
• Unable to find top command. Ensure you have a @CommandDefini
• Persistence unit '<persistenceUnitName>' was configured to r
• Failed to create Keycloak Admin client SSLContext
• Config property 'quarkus.mongodb.database' must be defined w

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