dromara/Sa-Token · error · SaTokenException

裁剪前缀长度必须小于 32 位

Error message

裁剪前缀长度必须小于 32 位

What it means

checkCutPrefixLength is called before creating a temporary token display string with a cut (recognition) prefix; it throws SaTokenException when the prefix is 32 characters or longer. The limit reserves room in the token string: the random token body plus prefix must fit fixed-length formats, so a 32+ char prefix would overflow them.

Source

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

		String key = splicingTempTokenSaveKey(token);
		SaManager.getSaTokenDao().deleteObject(key);
	}
	protected long _getTimeout(String token) {
		String key = splicingTempTokenSaveKey(token);
		return SaManager.getSaTokenDao().getObjectTimeout(key);
	}



	// -------- 其它

	/**
	 * 检查裁剪前缀长度
	 * @param cutPrefix /
	 */
	protected static void checkCutPrefixLength(String cutPrefix) {
		if(cutPrefix.length() >= 32) {
			throw new SaTokenException("裁剪前缀长度必须小于 32 位");
		}
	}

	/**
	 * 获取：在存储临时 token 数据时，应该使用的 key
	 * @param token token值
	 * @return key
	 */
	public String splicingTempTokenSaveKey(String token) {
		return SaManager.getConfig().getTokenName() + ":" + namespace + ":" + token;
	}

	/**
	 * @return jwt秘钥 (只有集成 sa-token-temp-jwt 模块时此参数才会生效)
	 */
	public String getJwtSecretKey() {
		return null;
	}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Shorten the prefix to < 32 characters (aim for a short stable marker like 'odr:')
2. Move long identifying data into the value parameter, not the cutPrefix
3. Add a startup/unit assertion on your prefix constant so regressions are caught before runtime

Example fix

// before
saTempTemplate.createToken(value, "order-payment-channel-2024-internal"); // 37 chars -> throws

// after
saTempTemplate.createToken(value, "opc:");

if (cutPrefix != null && cutPrefix.length() < 32) {
    saTempTemplate.createToken(value, cutPrefix);
} else {
    // shorten prefix: derive a short stable marker instead of the full business id
}

When it happens

Trigger: Calling SaTempTemplate.createToken(value, cutPrefix) (or a related API that funnels through checkCutPrefixLength) with a cutPrefix of length >= 32, e.g. a long business identifier used verbatim as the prefix.

Common situations: Using the full business key ('order-payment-channel-2024-...') as the cut prefix instead of a short marker; switching a previously short prefix to a namespaced one that crosses 31 chars.

Related errors

• namespace 不能为空
• 12002
• 12003
• 12001
• UsernameAndPassword 不能为空

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