dromara/Sa-Token · error · SaTokenException
UsernameAndPassword 格式错误，正确格式为：username:password
Error message
UsernameAndPassword 格式错误，正确格式为：username:password
What it means
The single-string SaHttpBasicAccount constructor splits its argument on ':' and requires exactly two parts. Zero colons (bare username), two or more colons (password containing ':' or stray separators), or a trailing-colon edge all make arr.length != 2 and throw this format exception.
Source
Thrown at sa-token-core/src/main/java/cn/dev33/satoken/httpauth/basic/SaHttpBasicAccount.java:59
* @param username 账号
* @param password 密码
*/
public SaHttpBasicAccount(String username, String password) {
this.username = username;
this.password = password;
}
/**
* 构造函数
* @param usernameAndPassword 账号和密码，冒号隔开
*/
public SaHttpBasicAccount(String usernameAndPassword) {
if(SaFoxUtil.isEmpty(usernameAndPassword)) {
throw new SaTokenException("UsernameAndPassword 不能为空");
}
String[] arr = usernameAndPassword.split(":");
if(arr.length != 2) {
throw new SaTokenException("UsernameAndPassword 格式错误，正确格式为：username:password");
}
this.username = arr[0];
this.password = arr[1];
}
/**
* 获取 账号
*
* @return username 账号
*/
public String getUsername() {
return this.username;
}
/**
* 设置 账号
*
* @param username 账号View on GitHub (pinned to ac2c7f6e94)
Solutions
- Use the two-argument constructor when either part may contain ':': new SaHttpBasicAccount(username, password)
- If passwords can contain ':', base64 or otherwise encode them before combining into the single-string form
- Add a startup assertion that the configured string has exactly one unescaped colon
Example fix
// before
new SaHttpBasicAccount("admin" + ":" + "pa:ss"); // 3 parts -> throws
// after
new SaHttpBasicAccount("admin", "pa:ss"); // parts passed explicitly Defensive patterns
Strategy: validation
Validate before calling
long colons = usernameAndPassword.chars().filter(c -> c == ':').count();
if (colons != 1) {
throw new IllegalArgumentException("need exactly one ':' in username:password");
} Prevention
- Use SaHttpBasicAccount(username, password) when either part may contain ':'
- Encode passwords containing colons before packing them into one string
- Add a config sanity check that rejects multi-colon credential values
When it happens
Trigger: new SaHttpBasicAccount("admin") — no colon; new SaHttpBasicAccount("admin:pa:ss") — password containing a colon; config value built by concatenating fields where one side already contained a colon.
Common situations: Passwords with ':' characters stored in config; hand-assembled credential strings; secrets from vaults that include URI-style 'user:pass@host' pasted wholesale.
Related errors
AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14).
Data as JSON: /api/errors/2c93066d8f3f4d63.
Report an issue: GitHub.