dromara/Sa-Token · critical

注解参数配置错误，格式应如：username:password

Error message

注解参数配置错误，格式应如：username:password

What it means

Startup-time fatal check in the (servlet-style reactive naming aside) sa-token-reactor-spring-boot-starter: its constructor reads SpringBootVersion.getVersion() and, if the running Spring Boot is 3.x or 4.x (anything not 1.x/2.x/empty), it throws SaTokenException telling you this starter artifact is only for Spring Boot 2. The class exists to fail fast instead of crashing later with NoSuchMethodError/ClassNotFoundException on Spring 6+ internals.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/annotation/handler/SaCheckHttpDigestHandler.java:48

 */
public class SaCheckHttpDigestHandler implements SaAnnotationHandlerInterface<SaCheckHttpDigest> {

    @Override
    public Class<SaCheckHttpDigest> getHandlerAnnotationClass() {
        return SaCheckHttpDigest.class;
    }

    @Override
    public void checkMethod(SaCheckHttpDigest at, AnnotatedElement element) {
        _checkMethod(at.username(), at.password(), at.realm(), at.value());
    }

    public static void _checkMethod(String username, String password, String realm, String value) {
        // 如果配置了 value，则以 value 优先
        if(SaFoxUtil.isNotEmpty(value)){
            String[] arr = value.split(":");
            if(arr.length != 2){
                throw new SaTokenException("注解参数配置错误，格式应如：username:password");
            }
            SaHttpDigestUtil.check(arr[0], arr[1]);
            return;
        }

        // 如果配置了 username，则分别获取参数
        if(SaFoxUtil.isNotEmpty(username)){
            SaHttpDigestUtil.check(username, password, realm);
            return;
        }

        // 都没有配置，则根据全局配置参数进行校验
        SaHttpDigestUtil.check();
    }

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Replace the dependency sa-token-reactor-spring-boot-starter with sa-token-reactor-spring-boot3-starter (or the -boot4- variant for Spring Boot 4) and rebuild
2. Verify the new artifact version matches your Sa-Token version (check the sa-token compatibility table for Spring Boot 3/4 support, 1.34+ provides boot3 starters)
3. After switching, confirm no other sa-token *-spring-boot-starter (non-boot3) artifacts remain transitively on the classpath (mvn dependency:tree | grep sa-token)

Example fix

<!-- before -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
    <version>1.38.0</version>
</dependency>

<!-- after -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-reactor-spring-boot3-starter</artifactId>
    <version>1.38.0</version>
</dependency>

// fail in CI/build, not at app startup
String v = org.springframework.boot.SpringBootVersion.getVersion();
if (v != null && !v.startsWith("1.") && !v.startsWith("2.")) {
    throw new IllegalStateException("Use sa-token-reactor-spring-boot3/4-starter, not sa-token-reactor-spring-boot-starter");
}

Not applicable: the exception is thrown from a bean constructor during startup; catching it only masks a guaranteed-broken classpath — fix the dependency instead

When it happens

Trigger: Including the Maven/Gradle artifact sa-token-reactor-spring-boot-starter on the classpath of an application whose Spring Boot version starts with 3. or 4.; the bean is instantiated during context startup and immediately throws, with the same message also printed to stderr.

Common situations: Upgrading a WebFlux project from Spring Boot 2 to 3/4 while keeping the old sa-token starter dependency; using a BOM or starter-parent that silently bumps Spring Boot; copying an old dependency block from a tutorial into a new project.

Related errors

• SPI 插件加载失败: " + e.getMessage()
• 未找到 Redisson 配置文件: ${file}
• CODE_30021

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