dromara/Sa-Token · critical · SaJwtException

请配置 jwt 秘钥

Error message

请配置 jwt 秘钥

What it means

Thrown by SaJwtTemplate.parseToken when the keyt (jwt secret key) parameter is empty. Every JWT operation in sa-token (sign, parse, verify) requires the configured secret, so this is a hard configuration error, not a token error. No error code is set (defaults to the generic jwt exception code).

Source

Thrown at sa-token-plugin/sa-token-jwt/src/main/java/cn/dev33/satoken/jwt/SaJwtTemplate.java:173

		return JWTSignerUtil.hs256(keyt.getBytes());
	}

	// ------ 解析 

    /**
     * jwt 解析
	 *
     * @param token Jwt-Token值 
     * @param loginType 登录类型 
     * @param keyt 秘钥
     * @param isCheckTimeout 是否校验 timeout 字段
     * @return 解析后的jwt 对象 
     */
    public JWT parseToken(String token, String loginType, String keyt, boolean isCheckTimeout) {

    	// 秘钥不可以为空
    	if(SaFoxUtil.isEmpty(keyt)) {
    		throw new SaJwtException("请配置 jwt 秘钥");
    	}

    	// 如果token为null 
    	if(token == null) {
    		throw new SaJwtException("jwt 字符串不可为空");
    	}
    	
    	// 解析 
    	JWT jwt;
    	try {
    		jwt = JWT.of(token);
		} catch (JWTException | JSONException e) {
    		throw new SaJwtException("jwt 解析失败：" + token, e).setCode(SaJwtErrorCode.CODE_30201);
		}
    	JSONObject payloads = jwt.getPayloads();
    	
    	// 校验 Token 签名
		boolean verify = jwt.setSigner(createSigner(keyt)).verify();

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Set sa-token.jwt-secret-key in your configuration (yml/properties) to a non-empty secret
2. If configuring programmatically, ensure the config object's jwtSecretKey is set before any JWT call
3. Use an environment variable for the secret and verify it is present in every deployment profile

Example fix

# before (application.yml)
sa-token:
  jwt-secret-key:   # empty -> throws

# after
sa-token:
  jwt-secret-key: ${SA_JWT_SECRET:please-change-me-32chars-min}

if (SaFoxUtil.isEmpty(saTokenConfig.getJwtSecretKey())) {
    throw new IllegalStateException("sa-token.jwt-secret-key must be configured"); // fail fast at startup
}

When it happens

Trigger: Any JWT-mode token parse/verification when sa-token's jwt-secret-key configuration is missing or empty — e.g. SaManager.getSaTokenConfigOrSecond() returns a config without jwt-secret-key, or the keyt argument passed programmatically is an empty string.

Common situations: Adding the sa-token-jwt dependency (Simple/Mixin/Stateless mode) but forgetting the 'jwt-secret-key' line in application.yml; environment-specific config where the secret env var is unset in one profile; programmatic use of SaJwtTemplate without supplying a key.

Related errors

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

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