dromara/Sa-Token · critical · JbootIllegalConfigException

can not connect to redis host {host}:{port} , cause : {e}

Error message

can not connect to redis host  {host}:{port} , cause : {e}

What it means

JbootIllegalConfigException from SaRedisCache.getJedis: borrowing a Jedis client from the pool raised JedisConnectionException, meaning the sa-token jboot plugin could not open a TCP connection to the configured Redis host:port. The cause chain carries the underlying connection error (refused, timeout, auth).

Source

Thrown at sa-token-starter/sa-token-jboot-plugin/src/main/java/cn/dev33/satoken/jboot/SaRedisCache.java:249

            if (scanKeys != null && scanKeys.size() > 0) {
                for (String key : scanKeys) {
                    keys.add(key.substring(3));
                }
            }

            if (redisScanResult.isCompleteIteration()) {
                continueState = false;
            }
        } while (continueState);

        return keys;
    }

    public Jedis getJedis() {
        try {
            return jedisPool.getResource();
        } catch (JedisConnectionException e) {
            throw new JbootIllegalConfigException("can not connect to redis host  " + config.getHost() + ":" + config.getPort() + " ," +
                    " cause : " + e, e);
        }
    }


    public void returnResource(Jedis jedis) {
        if (jedis != null) {
            jedis.close();
        }
    }

    public RedisScanResult<String> scan(String pattern, String cursor, int scanCount) {
        ScanParams params = new ScanParams();
        params.match(pattern).count(scanCount);
        try (Jedis jedis = getJedis()) {
            ScanResult<String> scanResult = jedis.scan(cursor, params);
            return new RedisScanResult<>(scanResult.getCursor(), scanResult.getResult());
        }

View on GitHub (pinned to ac2c7f6e94)

Solutions

  1. Verify reachability from the app host: redis-cli -h <host> -p <port> ping
  2. Correct jboot.redis.host / jboot.redis.port (and password/database) in jboot.properties
  3. In containerized deployments, point to the service name, not localhost, and check the Redis container logs

Example fix

# before (jboot.properties)
jboot.redis.host=127.0.0.1
jboot.redis.port=6379

# after
jboot.redis.host=redis.internal.example.com
jboot.redis.port=6379
jboot.redis.password=yourpassword
Defensive patterns

Strategy: retry

Validate before calling

try (Jedis j = new Jedis(host, port)) {
    j.ping(); // preflight at startup
} catch (Exception e) {
    // fail startup with explicit connectivity error
}

Try / catch

try { cache.getJedis(); } catch (JbootIllegalConfigException e) { /* backoff and retry; alert if persistent */ }

Prevention

When it happens

Trigger: Any sa-token cache operation (login, session read) in a Jboot app whose jboot.redis.host/port points to a Redis that is unreachable, firewalled, or requires a password that was not supplied.

Common situations: Redis not started / crashed; wrong host or port in jboot.properties; Docker/K8s networking where 'localhost' does not reach the Redis container; Redis requires a password but jboot.redis.password is empty.

Related errors

AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14). Data as JSON: /api/errors/5967e0afeff119c2. Report an issue: GitHub.