dromara/Sa-Token · error · SaSignException

nonce 为空，无效

Error message

nonce 为空，无效

What it means

Thrown by SaSignTemplate.checkNonce when the nonce parameter is empty/blank (SaSignException with no specific code). The anti-replay mechanism requires every signed request to carry a unique random nonce; an absent one cannot be recorded or checked, so the request is rejected immediately.

Source

Thrown at sa-token-plugin/sa-token-sign/src/main/java/cn/dev33/satoken/sign/template/SaSignTemplate.java:270

		// 为空代表无效
		if(SaFoxUtil.isEmpty(nonce)) {
			return false;
		}

		// 校验此 nonce 是否已被使用过
		String key = splicingNonceSaveKey(nonce);
		return SaManager.getSaTokenDao().get(key) == null;
	}

	/**
	 * 校验：随机字符串 nonce 是否有效，如果无效则抛出异常。
	 * 		注意：同一 nonce 只可以被校验通过一次，校验后将保存在缓存中，再次校验将无法通过
	 * @param nonce 待校验的随机字符串
	 */
	public void checkNonce(String nonce) {
		// 为空代表无效
		if(SaFoxUtil.isEmpty(nonce)) {
			throw new SaSignException("nonce 为空，无效");
		}

		// 校验此 nonce 是否已被使用过
		String key = splicingNonceSaveKey(nonce);
		if(SaManager.getSaTokenDao().get(key) != null) {
			throw new SaSignException("此 nonce 已被使用过，不可重复使用：" + nonce);
		}

		// 校验通过后，将此 nonce 保存在缓存中，保证下次校验无法通过
		SaManager.getSaTokenDao().set(key, nonce, getSignConfigOrGlobal().getSaveNonceExpire() * 2 + 2);
	}

	/**
	 * 判断：给定的参数 生成的签名是否为有效签名
	 * @param paramsMap 参数列表
	 * @param sign 待验证的签名
	 * @return 签名是否有效
	 */

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Include a fresh random nonce in every signed request: params.put("nonce", SaFoxUtil.getRandomString(32))
2. Ensure the nonce parameter name matches the configured one and is included in the signature computation and the HTTP payload
3. Regenerate nonce per request — never hardcode or reuse it

Example fix

// before
Map<String,String> p = buildBizParams(); String sign = createSign(p);
// after
p.put("nonce", SaFoxUtil.getRandomString(32));
p.put("timestamp", String.valueOf(System.currentTimeMillis()));
String sign = createSign(p);

if (SaFoxUtil.isEmpty(nonce)) throw new IllegalArgumentException("nonce is required for signed requests");

try { saSignTemplate.checkNonce(nonce); } catch (SaSignException e) { return status(401, "missing or invalid nonce"); }

When it happens

Trigger: Sending a signed API request where the nonce parameter is missing, empty string, or whitespace, e.g. after client code forgot to put it into the parameter map before signing.

Common situations: New client integration omits nonce from the signed parameter set; a filter strips unknown parameters; parameter name mismatch (nm vs nonce) between client convention and server config; copy-paste test code without the nonce entry.

Related errors

• 此 nonce 已被使用过，不可重复使用：{nonce}
• CODE_12203
• 12002
• 12003
• 12001

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