dromara/Sa-Token · warning · SaTokenException

12001

12001

Error message

缺少参数：" + name

What it means

SaRequest.getParamNotNull(name) is the interface-level required-parameter accessor: it fetches a request parameter and throws code 12001 when the value is null or empty. The exception names the missing parameter, making it a controlled bad-request signal rather than an infrastructure failure.

Source

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

	/**
	 * 在 [ 请求体 ] 里检测请求是否提供了指定参数
	 * @param name 参数名称 
	 * @return 是否提供 
	 */
	default boolean hasParam(String name) {
		 return SaFoxUtil.isNotEmpty(getParam(name));
	}
	
	/**
	 * 在 [ 请求体 ] 里获取一个值 （此值必须存在，否则抛出异常 ）
	 * @param name 键
	 * @return 参数值 
	 */
	default String getParamNotNull(String name) {
		String paramValue = getParam(name);
		if(SaFoxUtil.isEmpty(paramValue)) {
			throw new SaTokenException("缺少参数：" + name).setCode(SaErrorCode.CODE_12001);
		}
		return paramValue;
	}

	/**
	 * 获取 [ 请求体 ] 里提交的所有参数名称
	 * @return 参数名称列表
	 */
	Collection<String> getParamNames();

	/**
	 * 获取 [ 请求体 ] 里提交的所有参数
	 * @return 参数列表
	 */
	Map<String, String> getParamMap();

	/**
	 * 在 [ 请求头 ] 里获取一个值 

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Send the named parameter with a non-empty value in the request (query string, form body, or multipart as your framework binds)
2. In your code, prefer checking hasParam(name) first to return a friendly 400 message instead of the raw exception
3. Align parameter names across frontend/backend with a shared contract or constant

Example fix

// before
String ticket = SaHolder.getRequest().getParamNotNull("ticket"); // 500-style exception if absent

// after
SaRequest req = SaHolder.getRequest();
if (!req.hasParam("ticket")) {
    return SaResult.error("missing parameter: ticket");
}
String ticket = req.getParamNotNull("ticket");

SaRequest req = SaHolder.getRequest();
if (!req.hasParam("ticket")) {
    return SaResult.error("missing parameter: ticket");
}
String ticket = req.getParamNotNull("ticket");

try {
    String v = req.getParamNotNull("name");
} catch (SaTokenException e) {
    if (SaErrorCode.CODE_12001 == e.getCode()) { /* map to 400 response */ }
}

When it happens

Trigger: Custom controller/filter code calling SaHolder.getRequest().getParamNotNull("ticket") when the client omitted the parameter or sent an empty value; SSO/login endpoints requiring a param that the redirecting client did not append.

Common situations: Clients calling the API with a different parameter name (camelCase vs snake_case), form bodies missing fields, query strings dropped by a gateway rewrite, or frontend deploying one version ahead of backend.

Related errors

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

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