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 the legacy sa-token-alone-redis plugin when re-binding the separately-configured redis connection to the active SaTokenDao: it Class.forName-probes known dao implementations (ending with SaTokenDaoForRedisTemplate here), and if none loads, no supported sa-token-redis plugin is on the classpath. Identical semantics to error 113 but in the non-boot4 injector; the outer catch prints the stack trace rather than propagating cleanly.

Source

Thrown at sa-token-plugin/sa-token-alone-redis/src/main/java/cn/dev33/satoken/dao/alone/SaAloneRedisInject.java:232

				Class.forName("cn.dev33.satoken.dao.SaTokenDaoForRedisTemplateUseJdkSerializer");
				SaTokenDaoForRedisTemplateUseJdkSerializer dao = (SaTokenDaoForRedisTemplateUseJdkSerializer)saTokenDao;
				dao.isInit = false;
				dao.init(factory);
				return;
			} catch (ClassNotFoundException ignored) {
			}
			// 如果开发者引入的是：sa-token-redis-template
			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 RedisProperties getSaAloneRedisConfig() {
		return new RedisProperties();
	}
	
}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Add the matching sa-token-redis plugin dependency and pin all sa-token artifacts to one version.
2. Verify with mvn dependency:tree that the dao class (e.g. cn.dev33.satoken.dao.SaTokenDaoForRedisTemplate) is actually on the runtime classpath.
3. Check the printed stack trace at startup to distinguish this failure from an earlier connection error.
4. If your dao is custom, wire the alone-redis factory into it yourself instead of relying on the injector's probing.

Example fix

# before: only sa-token-alone-redis in pom

# after: add the dao plugin
<dependency>
  <groupId>cn.dev33</groupId>
  <artifactId>sa-token-redis-template</artifactId>
  <version>${sa-token.version}</version>
</dependency>

// CI/startup check for the legacy plugin
Class.forName("cn.dev33.satoken.dao.SaTokenDaoForRedisTemplate");
// and verify dependency:tree shows a sa-token-redis-* artifact at the same version

When it happens

Trigger: Using sa-token-alone-redis without a companion redis dao dependency (e.g. missing sa-token-redis-template / sa-token-redis-jackson etc. matching the probed class names), or with mismatched sa-token versions where the dao implementation class was relocated/renamed.

Common situations: Docs walkthrough that mentions alone-redis but omits the base redis plugin dependency; partial upgrades where sa-token-core version differs from the redis plugin version.

Related errors

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

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