dromara/Sa-Token · critical · SaTokenException

SaToken 无法识别 Alone-Redis 配置的模式: ${pattern}

Error message

SaToken 无法识别 Alone-Redis 配置的模式: ${pattern}

What it means

SaTokenException thrown by SaAloneRedisInject (spring-boot4 variant) when sa-token.alone-redis.pattern is none of the recognized values (standalone/cluster/sentinel/socket/aws variants). The if/else chain over pattern falls through to '模式无法识别', so any typo or unsupported deployment mode aborts startup.

Source

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

				redisSocketConfiguration.setPassword(RedisPassword.of(cfg.getPassword()));
				String socket = environment.getProperty(ALONE_PREFIX + ".socket", "");
				redisSocketConfiguration.setSocket(socket);

				redisAloneConfig = redisSocketConfiguration;
			} else if (pattern.equals("aws")) {
				// AWS ElastiCache
				// AWS Redis 远程主机地址: String hoseName = "****.***.****.****.cache.amazonaws.com";
				String hostName = cfg.getHost();
				int port = cfg.getPort();
				RedisStaticMasterReplicaConfiguration redisStaticMasterReplicaConfiguration = new RedisStaticMasterReplicaConfiguration(hostName, port);
				redisStaticMasterReplicaConfiguration.setDatabase(cfg.getDatabase());
				redisStaticMasterReplicaConfiguration.setUsername(cfg.getUsername());
				redisStaticMasterReplicaConfiguration.setPassword(RedisPassword.of(cfg.getPassword()));

				redisAloneConfig = redisStaticMasterReplicaConfiguration;
			} else {
				// 模式无法识别
				throw new SaTokenException("SaToken 无法识别 Alone-Redis 配置的模式: " + pattern);
			}

			// 2. 连接池配置
			GenericObjectPoolConfig poolConfig = new GenericObjectPoolConfig();
			// pool配置
			DataRedisProperties.Lettuce lettuce = cfg.getLettuce();
			if(lettuce.getPool() != null) {
				DataRedisProperties.Pool pool = cfg.getLettuce().getPool();
				// 连接池最大连接数
				poolConfig.setMaxTotal(pool.getMaxActive());
				// 连接池中的最大空闲连接
				poolConfig.setMaxIdle(pool.getMaxIdle());
				// 连接池中的最小空闲连接
				poolConfig.setMinIdle(pool.getMinIdle());
				// 连接池最大阻塞等待时间（使用负值表示没有限制）
				poolConfig.setMaxWaitMillis(pool.getMaxWait().toMillis());
			}
			LettucePoolingClientConfiguration.LettucePoolingClientConfigurationBuilder builder = LettucePoolingClientConfiguration.builder();

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Read the exact pattern string printed in the exception message and compare against the supported list in SaAloneRedisInject.
2. Use the correct literal (e.g. 'standalone', 'cluster', 'sentinel', 'socket') in lowercase with no surrounding spaces.
3. If you need master-replica, check whether your version supports the aws/static-master-replica branch and its exact pattern keyword.
4. Quoted or unquoted scalars are both fine in yaml, but ensure no trailing whitespace via block scalars.

Example fix

# before
sa-token:
  alone-redis:
    pattern: Cluster   # capital C -> unrecognized

# after
sa-token:
  alone-redis:
    pattern: cluster

Set<String> supported = Set.of("standalone", "cluster", "sentinel", "socket"); // per injector version
String p = props.getPattern();
if (!supported.contains(p)) { fail fast with the allowed list; }

boolean supportedPattern(String p, Set<String> allowed) { return p != null && allowed.contains(p.trim().toLowerCase()); }

When it happens

Trigger: Setting sa-token.alone-redis.pattern to a misspelled or unsupported value: 'Cluster' (capitalized), 'redis', 'master-slave', 'replication', or empty string after removing a comment incorrectly.

Common situations: Upgrading from the older sa-token-alone-redis plugin whose accepted pattern strings differ; hand-editing yml and introducing a typo; assuming a new Redis deployment mode is supported when only the enumerated ones are.

Related errors

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

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