dromara/Sa-Token · warning · SaSsoException

CODE_30014

CODE_30014

Error message

未指定 redirect 参数，也未配置 homeRoute 路由，无法完成重定向操作

What it means

Thrown on the sso-server when a user opens /sso/auth directly in the browser: the request has no redirect parameter and no homeRoute has been configured. With nowhere to send the user after login, the server cannot complete the flow and aborts.

Source

Thrown at sa-token-plugin/sa-token-sso/src/main/java/cn/dev33/satoken/sso/processor/SaSsoServerProcessor.java:129

		// 情况1，显示登录视图
		if( ! stpLogic.isLogin()) {
			return ssoServerTemplate.strategy.notLoginView.get();
		}

		// 情况2，开始跳转
		String mode = req.getParam(paramName.mode, SaSsoConsts.MODE_TICKET);
		String redirect = req.getParam(paramName.redirect);
		String client = req.getParam(paramName.client);

		// 构建最终重定向地址
		String redirectUrl = SaSugar.get(() -> {

			// 若 redirect 参数为空，说明用户并不是从 client 重定向来的，而是直接访问的 http://sso-server.com/sso/auth 地址
			// 此时需要跳转到配置的 homeRoute 路由上，
			// 若 homeRoute 也为空，则没有明确的跳转地址了，需要抛出异常
			if(SaFoxUtil.isEmpty(redirect)) {
				if(SaFoxUtil.isEmpty(cfg.getHomeRoute())) {
					throw new SaSsoException("未指定 redirect 参数，也未配置 homeRoute 路由，无法完成重定向操作").setCode(SaSsoErrorCode.CODE_30014);
				}
				return cfg.getHomeRoute();
			}

			// 方式1：直接重定向回Client端 (mode=simple，一般是模式一)
			if(mode.equals(SaSsoConsts.MODE_SIMPLE)) {
				ssoServerTemplate.checkRedirectUrl(client, redirect);
				return redirect;
			} else {
				// 方式2：带着 ticket 参数重定向回Client端 (mode=ticket，一般是模式二、三)

				// 构建并跳转
				String _redirectUrl = ssoServerTemplate.buildRedirectUrl(client, redirect, stpLogic.getLoginId(), stpLogic.getTokenValue());

				// 构建成功，说明 redirect 地址合法，此时需要更新一下当前 token 有效期
				if(cfg.getAutoRenewTimeout()) {
					stpLogic.renewTimeout(stpLogic.getConfigOrGlobal().getTimeout());
				}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Configure a fallback landing page on the server: sa-token.sso.server.home-route=/system/index (or sa-token.sso.home-route depending on version)
2. Enter the SSO flow through a client app so the redirect parameter is present, instead of opening /sso/auth directly

Example fix

# before (application.yml on sso-server)
sa-token:
  sso:
    server: {}   # no home-route

# after
sa-token:
  sso:
    home-route: /system/index

String redirect = req.getParam(paramName.redirect);
if(SaFoxUtil.isEmpty(redirect) && SaFoxUtil.isEmpty(cfg.getHomeRoute())) {
    // render a friendly page instead of letting the auth endpoint throw
}

When it happens

Trigger: Browser navigates to http://sso-server.com/sso/auth without a redirect query parameter while sa-token.sso.server.home-route is unset; typically a user bookmarked the login endpoint or opened it manually instead of being redirected from a client.

Common situations: First-time setup where the SSO server login page URL is visited directly; load balancer health checks hitting /sso/auth; missing home-route in application.yml for a deployment that expects direct logins.

Related errors

• client 标识不可为空
• CODE_30013
• CODE_30001
• CODE_30002
• CODE_30015

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