dromara/Sa-Token · critical · SaTokenException

请配置 sa-token.alone-redisson.config 或 sa-token.alone-redisson

Error message

请配置 sa-token.alone-redisson.config 或 sa-token.alone-redisson.file

What it means

SaTokenException thrown by SaAloneRedissonRegister.buildConfig when neither sa-token.alone-redisson.config (inline yaml string) nor sa-token.alone-redisson.file (file path) has a value. The register needs a Redisson-native Config to build the separate RedissonClient for alone-redis storage; with both blank it cannot construct one and fails fast. It is re-thrown as-is, distinct from the generic parse failure (error 117).

Source

Thrown at sa-token-plugin/sa-token-alone-redisson/src/main/java/cn/dev33/satoken/dao/alone/SaAloneRedissonRegister.java:83

		if (aloneClient != null && !aloneClient.isShuttingDown()) {
			aloneClient.shutdown();
		}
	}

	/**
	 * 解析 Redisson 原生 yaml：优先 config，其次 file
	 */
	public static Config buildConfig(SaAloneRedissonProperties properties) {
		try {
			Config config;
			if (StringUtils.hasText(properties.getConfig())) {
				config = Config.fromYAML(properties.getConfig());
			} else if (StringUtils.hasText(properties.getFile())) {
				try (InputStream in = openFile(properties.getFile())) {
					config = Config.fromYAML(in);
				}
			} else {
				throw new SaTokenException("请配置 sa-token.alone-redisson.config 或 sa-token.alone-redisson.file");
			}
			return config;
		} catch (SaTokenException e) {
			throw e;
		} catch (Exception e) {
			throw new SaTokenException("解析 sa-token.alone-redisson 配置失败", e);
		}
	}

	private static InputStream openFile(String file) throws Exception {
		String path = file.trim();
		Resource resource;
		if (path.startsWith("classpath:")) {
			resource = new ClassPathResource(path.substring("classpath:".length()));
		} else if (path.startsWith("file:")) {
			resource = new FileSystemResource(path.substring("file:".length()));
		} else {
			resource = new ClassPathResource(path);

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Add an inline config: sa-token.alone-redisson.config: |\n singleServerConfig:\n address: redis://127.0.0.1:6379 ...
2. Or point to a file: sa-token.alone-redisson.file: classpath:alone-redisson.yaml.
3. Check the exact property prefix is sa-token.alone-redisson (not alone-redis).
4. Ensure the value is non-blank after yaml parsing (no empty scalar).

Example fix

# before
sa-token:
  alone-redisson:
    # nothing configured -> throws

# after
sa-token:
  alone-redisson:
    config: |
      singleServerConfig:
        address: "redis://127.0.0.1:6381"
        database: 1
      threads: 4
      nettyThreads: 4

// before app context starts
if (!StringUtils.hasText(props.getConfig()) && !StringUtils.hasText(props.getFile())) {
    throw new IllegalStateException("set sa-token.alone-redisson.config or .file");
}

boolean hasRedissonSource(SaAloneRedissonProperties p) { return StringUtils.hasText(p.getConfig()) || StringUtils.hasText(p.getFile()); }

When it happens

Trigger: Adding sa-token-alone-redisson dependency without any sa-token.alone-redisson.* properties in application.yml; providing an empty string or only whitespace (StringUtils.hasText fails) for both properties.

Common situations: Assuming the plugin defaults to the primary Redisson config; setting properties under the wrong prefix (e.g. sa-token.alone-redis instead of sa-token.alone-redisson).

Related errors

• 解析 sa-token.alone-redisson 配置失败
• 未找到 Redisson 配置文件: ${file}
• 12002
• UsernameAndPassword 不能为空
• 未配置全局 Http Digest 认证参数

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