dromara/Sa-Token · error · SaTokenException

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

Error message

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

What it means

SaTokenException thrown by the deprecated checkByAnnotation(SaCheckHttpDigest) when the annotation's value() attribute is non-empty but does not split on ':' into exactly two parts. The value attribute must be strictly 'username:password'; anything else is a compile-time-style configuration mistake caught at runtime.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/httpauth/digest/SaHttpDigestTemplate.java:288

    // ----------------- 过期方法 -----------------

    /**
     * 根据注解 ( @SaCheckHttpDigest ) 鉴权
     *
     * @param at 注解对象
     */
    @Deprecated
    public void checkByAnnotation(SaCheckHttpDigest at) {

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

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

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

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Fix the annotation value to 'username:password' format, e.g. @SaCheckHttpDigest("admin:123456")
2. If the password contains a colon, use the named attributes instead: @SaCheckHttpDigest(username="admin", password="p@ss:word") — the username branch does not split on ':'
3. Prefer the non-deprecated API path (current interceptor handles the annotation directly); verify against your sa-token version's docs

Example fix

// before
@SaCheckHttpDigest("admin")   // no colon -> split length 1 -> exception

// after
@SaCheckHttpDigest("admin:123456")
// or
@SaCheckHttpDigest(username="admin", password="123456")

@SaCheckHttpDigest("admin:123456") // value must contain exactly one ':'
// programmatic check of an annotation before use:
String[] parts = at.value().split(":");
if (parts.length != 2) { /* reject */ }

When it happens

Trigger: Annotating a method/class with @SaCheckHttpDigest("someValue") where someValue has no colon or more than one colon. The value branch runs first (value takes priority over username/password attributes), so split(":").length != 2 throws immediately.

Common situations: Writing @SaCheckHttpDigest("admin password") with a space; a password containing ':' supplied via value; misunderstanding that value must be 'user:pass' and instead putting a realm or role name there; upgrading from versions where the attribute semantics differed.

Related errors

• 未配置全局 Http Digest 认证参数
• 全局 Http Digest 认证参数配置错误，格式应如：username:password
• 12002
• UsernameAndPassword 不能为空
• 10312

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