dromara/Sa-Token · critical · SaTokenException

未引入 sa-token-redis-xxx 相关插件，或引入的插件不在 Alone-Redis 支持范围内

Error message

未引入 sa-token-redis-xxx 相关插件，或引入的插件不在 Alone-Redis 支持范围内

What it means

SaTokenException thrown by SaAloneRedisInject (spring-boot4 variant) during re-injection of the alone-redis connection factory into the active SaTokenDao: it probes for known dao classes (SaTokenDaoForRedisTemplate and siblings) via Class.forName, and if none is present on the classpath it concludes no supported sa-token-redis plugin was introduced. Each probe failure is silently swallowed (ClassNotFoundException ignored) before this terminal throw.

Source

Thrown at sa-token-plugin/sa-token-alone-redis-by-spring-boot4/src/main/java/cn/dev33/satoken/dao/alone/SaAloneRedisInject.java:212

			try {
				Class.forName("cn.dev33.satoken.dao.SaTokenDaoForRedisTemplateUseJdkSerializer");
				SaTokenDaoForRedisTemplate dao = (SaTokenDaoForRedisTemplate) saTokenDao;
				dao.isInit = false;
				dao.init(factory);
				return;
			} catch (ClassNotFoundException ignored) {
			}
			try {
				Class.forName("cn.dev33.satoken.dao.SaTokenDaoForRedisTemplate");
				SaTokenDaoForRedisTemplate dao = (SaTokenDaoForRedisTemplate) saTokenDao;
				dao.isInit = false;
				dao.init(factory);
				return;
			} catch (ClassNotFoundException ignored) {
			}

			// 至此，说明开发者一个 redis 插件也没引入，或者引入的 redis 插件不在 sa-token-alone-redis 的支持范围内
			throw new SaTokenException("未引入 sa-token-redis-xxx 相关插件，或引入的插件不在 Alone-Redis 支持范围内");

		} catch (Exception e) {
			e.printStackTrace();
		}
	}

	/**
	 * 骗过编辑器，增加配置文件代码提示
	 * @return 配置对象
	 */
	@ConfigurationProperties(prefix = ALONE_PREFIX)
	public DataRedisProperties getSaAloneRedisConfig() {
		return new DataRedisProperties();
	}

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Add a supported redis dao dependency, e.g. sa-token-redis-template (or the packaged dao matching your stack) alongside sa-token-alone-redis-by-spring-boot4.
2. Align versions: use the same sa-token version for all sa-token-* artifacts so class names match the ones probed.
3. Scan the startup log for the printed stack trace to confirm this throw (and not an earlier swallowed CNFE) is the real blocker.
4. If you intentionally use a custom dao, it is not 'alone-injectable' — connect it to the separate redis manually instead of relying on this auto-injection.

Example fix

# before (pom)
<dependency>
  <groupId>cn.dev33</groupId>
  <artifactId>sa-token-alone-redis-by-spring-boot4</artifactId>
</dependency>

# after
<dependency>
  <groupId>cn.dev33</groupId>
  <artifactId>sa-token-alone-redis-by-spring-boot4</artifactId>
</dependency>
<dependency>
  <groupId>cn.dev33</groupId>
  <artifactId>sa-token-redis-template</artifactId>
  <version>${sa-token.version}</version>
</dependency>

// in a CI/startup smoke test
Class.forName("cn.dev33.satoken.dao.SaTokenDaoForRedisTemplate"); // throws if dao plugin missing
// plus assert all sa-token-* artifacts share one version

When it happens

Trigger: Adding sa-token-alone-redis-by-spring-boot4 to the project without also adding a redis dao plugin such as sa-token-redis-template (or adding an out-of-support one, e.g. a Jackson dao variant whose class name is not probed). Note the surrounding try/catch prints the stack trace via e.printStackTrace() and may mask this exception in logs.

Common situations: Following the alone-redis docs but skipping the prerequisite '集成 sa-token-redis 插件' step; mixing plugin versions where the dao class was renamed/moved between majors.

Related errors

• 未引入 sa-token-redis-xxx 相关插件，或引入的插件不在 Alone-Redis 支持范围内
• Alone-Redis 集群模式需要配置 cluster.nodes
• Alone-Redis 哨兵模式需要配置 sentinel.nodes
• SaToken 无法识别 Alone-Redis 配置的模式: ${pattern}
• 验证码错误

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