dromara/Sa-Token · error · JbootIllegalConfigException

Please config "jboot.redis.{cacheName}.host" in your jboot.p

Error message

Please config "jboot.redis.{cacheName}.host" in your jboot.properties.

What it means

JbootIllegalConfigException from the SaTokenCacheDao constructor: the requested named Redis cache (cacheName, default 'default') has no corresponding jboot.redis.<cacheName>.* configuration block in jboot.properties. The DAO double-checks the map after the lock and fails fast because ConfigUtil returned no JbootRedisConfig for that name.

Source

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

        JbootRedisConfig config = Jboot.config(JbootRedisConfig.class);
        this.saRedisCache = new SaRedisCache(config);
        this.serializer = new SaJdkSerializer();
    }

    /**
     * 调用的Cache名称
     *
     * @param cacheName 使用的缓存配置名，默认为 default
     */
    public SaTokenCacheDao(String cacheName) {
        SaRedisCache saCache = this.saRedisMap.get(cacheName);
        if (saCache == null) {
            synchronized (this) {
                saCache = this.saRedisMap.get(cacheName);
                if (saCache == null) {
                    Map<String, JbootRedisConfig> configModels = ConfigUtil.getConfigModels(JbootRedisConfig.class);
                    if (!configModels.containsKey(cacheName)) {
                        throw new JbootIllegalConfigException("Please config \"jboot.redis." + cacheName + ".host\" in your jboot.properties.");
                    }

                    JbootRedisConfig jbootRedisConfig = configModels.get(cacheName);
                    saCache = new SaRedisCache(jbootRedisConfig);
                    this.saRedisMap.put(cacheName, saCache);
                }
            }
        }
        this.saRedisCache = saCache;
        this.serializer = new SaJdkSerializer();
    }


    @Override
    public String get(String key) {
        Jedis jedis = saRedisCache.getJedis();
        try {
            return jedis.get(key);

View on GitHub (pinned to ac2c7f6e94)

Solutions

Add a config block for the exact name: jboot.redis.<cacheName>.host=... (plus port/password as needed)
Check the spelling/case of cacheName in code against the properties key — they must match exactly
Use the default name or ensure every named cache used by sa-token has its block

Example fix

# before (jboot.properties)
jboot.redis.default.host=127.0.0.1
# code used new SaTokenCacheDao("sso-cache")

# after
jboot.redis.default.host=127.0.0.1
jboot.redis.sso-cache.host=127.0.0.1
jboot.redis.sso-cache.port=6379

Defensive patterns

Strategy: validation

Validate before calling

Map<String, JbootRedisConfig> m = ConfigUtil.getConfigModels(JbootRedisConfig.class);
if(!m.containsKey(cacheName)) {
    // fail startup listing the missing jboot.redis.<cacheName> block
}

Prevention

Define every named redis cache block in jboot.properties before referencing it in code
Use constants for cache names so code and properties cannot drift

When it happens

Trigger: Constructing new SaTokenCacheDao("mycache") when jboot.properties lacks a jboot.redis.mycache.host entry; or the default cache name is changed without adding the matching config block.

Common situations: Renaming the sa-token cache in a Jboot app without adding the new Redis block; typo between the cacheName string in code and the properties key; copying a properties template that only defines some named caches.

Related errors

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