dromara/Sa-Token · error · NotImplException

12401

12401

Error message

未实现具体路由匹配策略

What it means

sa-token-core ships only a default no-op route matcher that throws NotImplException (code 12401) whenever SaStrategy.routeMatcher is invoked. The library expects the framework integration layer (spring-boot-starter, reactor starter, solon/jfinal/jboot plugins) to replace this strategy at startup with a real implementation such as AntPathMatcher or Spring PathPattern. If you use sa-token-core directly or the integration failed to register, any route-interceptor matching (SaRouter.match, checkPath annotations, SaInterceptor) hits this throw.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/strategy/SaStrategy.java:184

	/**
     * 是否自动续期 active-timeout
     */
    public SaAutoRenewFunction autoRenew = (stpLogic) -> {
        return stpLogic.getConfigOrGlobal().getAutoRenew();
    };

	/**
	 * 创建 StpLogic 的算法
	 */
	public SaCreateStpLogicFunction createStpLogic = (loginType) -> {
		return new StpLogic(loginType);
	};

	/**
	 * 路由匹配策略
	 */
	public SaRouteMatchFunction routeMatcher = (pattern, path) -> {
		throw new NotImplException("未实现具体路由匹配策略").setCode(SaErrorCode.CODE_12401);
	};

	/**
	 * CORS 策略处理函数
	 */
	public SaCorsHandleFunction corsHandle = (req, res, sto) -> {

	};


	// ----------------------- 重写策略 set连缀风格

	/**
	 * 重写创建 Token 的策略
	 *
	 * @param createToken /
	 * @return /
	 */

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Use the matching integration starter (sa-token-spring-boot-starter, sa-token-reactor-spring-boot-starter, sa-token-solon-plugin, etc.) — its SaTokenContextRegister/SaBeanRegister sets routeMatcher automatically
2. If no official plugin exists for your framework, assign one yourself at startup: SaStrategy.instance.routeMatcher = (pattern, path) -> AntPathMatcher.INSTANCE.match(pattern, path);
3. Verify the registration actually ran (debug-print SaStrategy.instance.routeMatcher) and that your auto-configuration is not excluded via spring.autoconfigure.exclude
4. For Spring 6+, bind it to PathPatternParser: SaStrategy.instance.routeMatcher = new SaPathPatternParser()::match

Example fix

// before: only sa-token-core on classpath, then
SaRouter.match("/admin/**", r -> StpUtil.checkRole("admin")); // throws 12401

// after: assign a matcher at app startup
@Bean
public void initSaStrategy() {
    SaStrategy.instance.routeMatcher = (pattern, path) ->
        AntPathMatcher.INSTANCE.match(pattern, path);
}

// before app start, verify the integration set a real matcher
if (SaStrategy.instance.routeMatcher == null
        || SaStrategy.instance.routeMatcher.apply("/a", "/a") == null) {
    // default throws NotImplException, so test via exception:
}
try {
    SaStrategy.instance.routeMatcher.apply("/test/**", "/test/x");
} catch (NotImplException e) {
    SaStrategy.instance.routeMatcher = (pattern, path)
        -> AntPathMatcher.INSTANCE.match(pattern, path);
}

try {
    SaRouter.match("/admin/**", r -> StpUtil.checkRole("admin"));
} catch (NotImplException e) {
    // config error, not a business condition: fail startup loudly
    throw new IllegalStateException("routeMatcher not installed; add a sa-token starter", e);
}

When it happens

Trigger: Calling SaRouter.match("/user/**") or registering a SaInterceptor with route rules while SaStrategy.instance.routeMatcher was never assigned; depending on sa-token-core alone without a sa-token-starter/sa-token-plugin integration module; manually constructing SaManager components before the Spring/solon context registers SaTokenContextRegister/SaBeanRegister.

Common situations: Adding sa-token-core as the only dependency (e.g. in a plain Java or Vert.x/gRPC app with no official plugin); integration auto-configuration not loading because the starter is not on the component-scan path or the context is a non-web @SpringBootApplication; upgrading and accidentally swapping the starter for core.

Related errors

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

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