dromara/Sa-Token · error · SaTokenException

12002

12002

Error message

name不能为空

What it means

SaCookie.toHeaderValue() serializes the cookie for the Set-Cookie header and first runs builder(). If the cookie's name is null/empty at that point it throws code 12002, because a Set-Cookie line without a name is unparseable by browsers. This is a programming/config error in how the SaCookie was constructed.

Source

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

	/**
	 * 构建一下
	 */
	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);

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Always set the name: new SaCookie().setName(StpUtil.getTokenName()).setValue(v)...
2. Check application config: sa-token.token-name must be non-empty (it is also the cookie name by default)
3. For cookie deletion, set name and maxAge=0 explicitly rather than building an anonymous cookie

Example fix

// before
SaCookie cookie = new SaCookie().setValue("").setMaxAge(0);
SaHolder.getResponse().addCookie(cookie); // CODE_12002

// after
SaCookie cookie = new SaCookie()
        .setName(StpUtil.getTokenName())
        .setValue("")
        .setMaxAge(0);
SaHolder.getResponse().addCookie(cookie);

if (SaFoxUtil.isEmpty(cookie.getName())) {
    throw new IllegalArgumentException("SaCookie name required before toHeaderValue()");
}

When it happens

Trigger: new SaCookie().setValue("x").toHeaderValue(); or code that builds the token cookie from config where the token-name config item is empty (token-name= in yml/properties) and is copied into SaCookie.setName(null).

Common situations: Custom cookie writing in logout/login hooks that forgets setName(); an empty sa-token.token-name configuration; resetting a cookie via new SaCookie() and only setting maxAge=0 for deletion without naming it.

Related errors

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

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