dromara/Sa-Token · error · SaTokenException

全局 Http Digest 认证参数配置错误，格式应如：username:password

Error message

全局 Http Digest 认证参数配置错误，格式应如：username:password

What it means

SaTokenException thrown by SaHttpDigestTemplate.check() when the global 'httpDigest' config string does not split on ':' into exactly two parts. The config must be strictly 'username:password' — the implementation uses httpDigest.split(":") and requires arr.length == 2, so any extra or missing colon is rejected before authentication runs.

Source

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

     * @param username 用户名
     * @param password 密码
     * @param realm 领域
     */
    public void check(String username, String password, String realm) {
        check(new SaHttpDigestModel(username, password, realm));
    }

    /**
     * 校验：根据全局配置参数，校验不通过抛出异常
     */
    public void check() {
        String httpDigest = SaManager.getConfig().getHttpDigest();
        if(SaFoxUtil.isEmpty(httpDigest)){
            throw new SaTokenException("未配置全局 Http Digest 认证参数");
        }
        String[] arr = httpDigest.split(":");
        if(arr.length != 2){
            throw new SaTokenException("全局 Http Digest 认证参数配置错误，格式应如：username:password");
        }
        check(arr[0], arr[1]);
    }



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

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

        // 如果配置了 value，则以 value 优先
        String value = at.value();

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Ensure the value is exactly one username, one colon, one password: sa-token.http-digest=admin:123456
2. If the password must contain a colon, do not use the global config — use @SaCheckHttpDigest(username=..., password=...) or call check(username, password) programmatically where both are separate strings
3. Double-check for typos, trailing colons, or accidental extra segments in the YAML/properties value

Example fix

# before
sa-token:
  http-digest: admin:p@ss:word   # password contains ':' -> arr.length==3 -> exception

# after
sa-token:
  http-digest: admin:p@ssword    # colon-free password
# or bypass global config:
@SaCheckHttpDigest(username="admin", password="p@ss:word")

String httpDigest = SaManager.getConfig().getHttpDigest();
boolean valid = httpDigest != null && httpDigest.split(":").length == 2;
if (!valid) { /* reject config at startup */ }

When it happens

Trigger: Setting sa-token.http-digest to a value with zero colons (e.g. 'admin123') or two-plus colons (e.g. 'admin:pass:extra', or a password that itself contains ':' such as 'admin:p@ss:word'), then invoking the no-arg check().

Common situations: Password containing a colon makes the split produce 3 parts; typo like 'admin password' with a space instead of colon; copy-pasting a URL like 'http://...' into the value; trailing colon 'admin:'.

Related errors

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

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