dromara/Sa-Token · error · SaTokenException

未配置全局 Http Digest 认证参数

Error message

未配置全局 Http Digest 认证参数

What it means

SaTokenException thrown by the no-arg SaHttpDigestTemplate.check() when the global configuration item 'httpDigest' is empty. The no-arg check() is designed to validate against credentials stored in the global Sa-Token config (format username:password), so it refuses to run when that config is missing.

Source

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

    }

    /**
     * 校验：根据提供的参数，校验不通过抛出异常
     * @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

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Set the global config, e.g. in application.yml: sa-token: http-digest: username:password (or sa-token.http-digest=username:password in properties)
2. Or specify credentials per-annotation: @SaCheckHttpDigest(username="admin", password="123456") or @SaCheckHttpDigest("admin:123456")
3. Or call the explicit overload check(username, password) / check(model) instead of the no-arg check()

Example fix

// before
@SaCheckHttpDigest
@GetMapping("/data")
public SaResult data() { ... }
// application.yml has no http-digest -> exception

// after
# application.yml
sa-token:
  http-digest: admin:123456

String httpDigest = SaManager.getConfig().getHttpDigest();
if (SaFoxUtil.isEmpty(httpDigest)) {
    // fail fast at startup with a clear message, or skip the no-arg check()
}

try {
    saTokenHttpDigestTemplate.check();
} catch (SaTokenException e) {
    if ("未配置全局 Http Digest 认证参数".equals(e.getMessage())) { /* config missing: fix config */ }
    throw e;
}

When it happens

Trigger: Calling saTokenHttpDigestTemplate.check() (no arguments) while SaManager.getConfig().getHttpDigest() returns null or empty string. This happens when using @SaCheckHttpDigest with neither value nor username attributes, which makes the interceptor fall back to the global-config check().

Common situations: Adding @SaCheckHttpDigest to a controller without specifying value/username/realm and forgetting to set sa-token.http-digest in application.yml/properties; migrating config where the http-digest key was renamed or dropped; environment-specific config files (dev/prod) where only one defines the key.

Related errors

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

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