dromara/Sa-Token · error · SaOAuth2Exception

30101

30101

Error message

client_id 不可为空

What it means

Thrown by RequestAuthModel.checkModel() when the clientId field is empty. The OAuth2 server builds a RequestAuthModel for every authorize/token flow and self-checks it before generating code or tokens; an empty client_id fails the first check. Error code 30101.

Source

Thrown at sa-token-plugin/sa-token-oauth2/src/main/java/cn/dev33/satoken/oauth2/data/model/request/RequestAuthModel.java:189

		return nonce;
	}

	/**
	 * @param nonce 要设置的随机数
	 * @return 对象自身
	 */
	public RequestAuthModel setNonce(String nonce) {
		this.nonce = nonce;
		return this;
	}

	/**
	 * 数据自检
	 * @return 对象自身
	 */
	public RequestAuthModel checkModel() {
		if(SaFoxUtil.isEmpty(clientId)) {
			throw new SaOAuth2Exception("client_id 不可为空").setCode(SaOAuth2ErrorCode.CODE_30101);
		}
		if(SaFoxUtil.isEmpty(scopes)) {
			throw new SaOAuth2Exception("scope 不可为空").setCode(SaOAuth2ErrorCode.CODE_30102);
		}
		if(SaFoxUtil.isEmpty(redirectUri)) {
			throw new SaOAuth2Exception("redirect_uri 不可为空").setCode(SaOAuth2ErrorCode.CODE_30103);
		}
		if(SaFoxUtil.isEmpty(String.valueOf(loginId))) {
			throw new SaOAuth2Exception("LoginId 不可为空").setCode(SaOAuth2ErrorCode.CODE_30104);
		}
		return this;
	}

	@Override
	public String toString() {
		return "RequestAuthModel{" +
				"clientId='" + clientId + '\'' +
				", scopes=" + scopes +

View on GitHub (pinned to ac2c7f6e94)

Solutions

  1. Ensure the authorize request includes a non-empty client_id parameter that matches a registered SaClientModel
  2. If building RequestAuthModel manually, set ra.clientId (or call setClientId) before checkModel()/generateAccessToken()
  3. Check the actual outgoing request URL/params (browser network tab or gateway logs) to confirm client_id is present

Example fix

// before
http://host/oauth2/authorize?response_type=code&redirect_uri=...

// after
http://host/oauth2/authorize?response_type=code&client_id=1001&redirect_uri=...
Defensive patterns

Strategy: validation

Validate before calling

// before building/sending the authorize request
if(SaFoxUtil.isEmpty(clientId)) {
    throw new IllegalArgumentException("client_id is required");
}

Try / catch

try {
    oauth2Template or processor call
} catch(SaOAuth2Exception e) {
    if(e.getCode().equals("30101")) { /* return 400 with client_id hint */ }
}

Prevention

When it happens

Trigger: Calling the /oauth2/authorize endpoint without a client_id request parameter, or programmatically building a RequestAuthModel and calling checkModel() without setClientId(). Also happens when a custom grant-type handler forgets to set ra.clientId before token generation.

Common situations: Misconfigured authorize URL in the client app, a typo in the parameter name (e.g. clientId instead of client_id), or a reverse proxy stripping query parameters.

Related errors

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