dromara/Sa-Token · error · SaTokenException

12003

12003

Error message

无效Value：" + value

What it means

SaCookie.toHeaderValue() rejects any cookie value containing ';' (code 12003). ';' is the delimiter inside the Set-Cookie header, so embedding it would split/forge the cookie attributes; sa-token fails fast instead of emitting a broken header.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/context/model/SaCookie.java:325

	 */
	public void builder() {
		if(path == null) {
			path = "/";
		}
	}

	/**
	 * 转换为响应头 Set-Cookie 参数需要的值
	 * @return /
	 */
	public String toHeaderValue() {
		this.builder();

		if(SaFoxUtil.isEmpty(name)) {
			throw new SaTokenException("name不能为空").setCode(SaErrorCode.CODE_12002);
		}
		if(value != null && value.contains(";")) {
			throw new SaTokenException("无效Value：" + value).setCode(SaErrorCode.CODE_12003);
		}

		// example：
		// Set-Cookie: name=value; Max-Age=100000; Expires=Tue, 05-Oct-2021 20:28:17 GMT; Domain=localhost; Path=/; Secure; HttpOnly; SameSite=Lax

		StringBuilder sb = new StringBuilder();
		sb.append(name).append("=").append(value);

		if(maxAge >= 0) {
			 sb.append("; Max-Age=").append(maxAge);
			 String expires;
			 if(maxAge == 0) {
				 expires = Instant.EPOCH.atOffset(ZoneOffset.UTC).format(DateTimeFormatter.RFC_1123_DATE_TIME);
			 } else {
				 expires = OffsetDateTime.now().plusSeconds(maxAge).format(DateTimeFormatter.RFC_1123_DATE_TIME);
			 }
			 sb.append("; Expires=").append(expires);
		}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. URL-encode the value before setting: SaFoxUtil.encodeUrl(value) or java.net.URLEncoder.encode(value, StandardCharsets.UTF_8)
2. Use a safe separator (e.g. '&' or '|') and still encode the whole value
3. Prefer storing opaque tokens (UUID/JWT without ';') in cookies and keeping structured data server-side

Example fix

// before
SaCookie cookie = new SaCookie().setName("auth").setValue(userInput); // userInput = "a;b"

// after
SaCookie cookie = new SaCookie().setName("auth").setValue(SaFoxUtil.encodeUrl(userInput));

if (value != null && value.contains(";")) {
    value = SaFoxUtil.encodeUrl(value); // or reject
}

When it happens

Trigger: SaCookie.setValue("a;b") followed by toHeaderValue()/addCookie; building an auth or ticket cookie from user-controlled input that may contain ';', e.g. value = username + ";" + role.

Common situations: Composing multi-part values with ';' as separator instead of URL-encoding; passing an unparsed Authorization header or JWT fragment (which can contain base64 ';'-adjacent data) into a cookie; copying values from another cookie verbatim.

Related errors

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

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