dromara/Sa-Token · error · SaTokenException

namespace 不能为空

Error message

namespace 不能为空

What it means

SaTempTemplate (Sa-Token's temporary-token / temp-session feature) is constructed with a namespace used to isolate its stored data. Both constructors validate the namespace: the no-arg constructor uses DEFAULT_NAMESPACE, but the String constructor throws SaTokenException when given null or empty. This is a fail-fast guard against misconfiguration, not a runtime state error.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/temp/SaTempTemplate.java:71

	 */
	public SaRawSessionDelegator rawSessionDelegator;

	/**
	 * 在 raw-session 中的保存索引列表使用的 key
	 */
	public static final String TEMP_TOKEN_MAP = "__HD_TEMP_TOKEN_MAP";

	public SaTempTemplate(){
		this(DEFAULT_NAMESPACE);
	}

	/**
	 * 实例化
	 * @param namespace 命名空间，用于多实例隔离
	 */
	public SaTempTemplate(String namespace){
		if(SaFoxUtil.isEmpty(namespace)) {
			throw new SaTokenException("namespace 不能为空");
		}
		this.namespace = namespace;
		this.rawSessionDelegator = new SaRawSessionDelegator(namespace);
	}


	// -------- 创建

	/**
	 * 为指定 value 创建一个临时 token (如果多条业务线均需要创建临时 token，请自行在 value 拼接不同前缀)
	 *
	 * @param value 指定值
	 * @param timeout 有效时间，单位：秒，-1 代表永久有效
	 * @return 生成的 token
	 */
	public String createToken(Object value, long timeout) {
		return createToken(value, timeout, false);
	}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Pass a non-empty namespace string, e.g. new SaTempTemplate("order-service")
2. Use the no-arg constructor new SaTempTemplate() if you do not need namespace isolation
3. Validate/derive the namespace from config with a sensible required-value check at startup

Example fix

// before
String ns = System.getenv("TEMP_NS"); // null in prod
new SaTempTemplate(ns);

// after
String ns = Optional.ofNullable(System.getenv("TEMP_NS")).orElse("default");
new SaTempTemplate(ns);

if (SaFoxUtil.isEmpty(namespace)) {
    throw new IllegalArgumentException("TEMP_NS config missing");
}
SaTempTemplate t = new SaTempTemplate(namespace);

When it happens

Trigger: Calling new SaTempTemplate(null) or new SaTempTemplate(""); also a subclass calling super(namespace) with a namespace computed from config that is missing or blank.

Common situations: Building a custom multi-namespace temp-token setup where the namespace is read from a config key that is absent in some environment; passing a trimmed/empty string from an env variable.

Related errors

• 12002
• UsernameAndPassword 不能为空
• 全局 Http Digest 认证参数配置错误，格式应如：username:password
• 裁剪前缀长度必须小于 32 位
• 12003

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