dromara/Sa-Token · error · RequestPathInvalidException

非法请求：{requestPath}

Error message

非法请求：{requestPath}

What it means

The default firewall in sa-token runs a set of check hooks on every request; the BlackPath hook compares the exact request path against the configured blackPath list and throws RequestPathInvalidException on an exact match. This is a security control meant to block well-known sensitive endpoints (e.g. /actuator/health) at the framework level. The exception message includes the offending path so you can immediately see which rule fired.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/strategy/hooks/SaFirewallCheckHookForBlackPath.java:65

     */
    public void resetConfig(String... paths) {
        this.blackPaths.clear();
        this.blackPaths.addAll(Arrays.asList(paths));
    }

    /**
     * 执行的方法
     *
     * @param req 请求对象
     * @param res 响应对象
     * @param extArg 扩展预留参数
     */
    @Override
    public void execute(SaRequest req, SaResponse res, Object extArg) {
        String requestPath = req.getRequestPath();
        for (String item : blackPaths) {
            if (requestPath.equals(item)) {
                throw new RequestPathInvalidException("非法请求：" + requestPath, requestPath);
            }
        }

    }

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Remove or rename the offending entry in the sa-token.firewall.black-path config list
2. If the path must stay public, change your endpoint path so it no longer equals the blacklisted string
3. For infra probes, point the liveness/readiness probe at a different, unblacklisted actuator path

Example fix

# before (application.yml)
sa-token:
  firewall:
    black-path:
      - /actuator/health

# after
sa-token:
  firewall:
    black-path:
      - /actuator/env

String path = SaHolder.getRequest().getRequestPath();
List<String> black = SaManager.getConfig().getFirewall().getBlackPath();
if (black.contains(path)) {
    // reject early with your own 404/403 response
}

try {
    chain.doFilter(req, res);
} catch (RequestPathInvalidException e) {
    res.setStatus(404); // do not echo the path back; log it instead
}

When it happens

Trigger: A request whose path string-exactly equals an entry in sa-token.firewall.black-path (e.g. property sa-token.firewall.black-path[0]=/druid/index.html and a GET to /druid/index.html). Only exact equality matches — no wildcards.

Common situations: Default blacklist entries like /actuator/health being hit by Kubernetes liveness probes or monitoring; a legitimately added public endpoint that shares a name with a default black path; copying a blacklist from another project that blocks a path your app actually serves.

Related errors

• 非法请求：{requestPath}
• 请求 path 包含禁止字符：{requestPath}
• 请求 path 包含禁止字符 %：{requestPath}
• 非法请求：{requestPath}
• 非法请求头：{headerName}

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