dromara/Sa-Token · error · FirewallCheckException

非法请求 Method：{method}

Error message

非法请求 Method：{method}

What it means

When sa-token.firewall.check-method is enabled, the HTTP Method firewall hook requires req.getMethod() to be present in the configured allowMethods collection, otherwise it throws FirewallCheckException naming the method. The method name is case-sensitive: the raw servlet method is uppercase, so lowercase entries in your config list will never match.

Source

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

    public void resetConfig(boolean isCheckMethod, String... methods) {
        this.isCheckMethod = isCheckMethod;
        this.allowMethods.clear();
        this.allowMethods.addAll(Arrays.asList(methods));
    }

    /**
     * 执行的方法
     *
     * @param req 请求对象
     * @param res 响应对象
     * @param extArg 预留扩展参数
     */
    @Override
    public void execute(SaRequest req, SaResponse res, Object extArg) {
        if(isCheckMethod) {
            String method = req.getMethod();
            if( ! allowMethods.contains(method) ) {
                throw new FirewallCheckException("非法请求 Method：" + method);
            }
        }
    }

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Add the blocked method (uppercase) to sa-token.firewall.allow-methods, e.g. [GET, POST, PUT, DELETE, OPTIONS]
2. Always include OPTIONS when the API is called cross-origin from browsers
3. Or turn the check off (method-check=false) if you cannot enumerate methods

Example fix

# before
sa-token:
  firewall:
    check-method: true
    allow-methods: [GET, POST]

# after
sa-token:
  firewall:
    check-method: true
    allow-methods: [GET, POST, PUT, DELETE, PATCH, OPTIONS]

String m = req.getMethod().toUpperCase(Locale.ROOT);
if (SaManager.getConfig().getFirewall().getIsCheckMethod()
        && !SaManager.getConfig().getFirewall().getAllowMethods().contains(m)) {
    // reject 405 before sa-token firewall
}

try {
    chain.doFilter(req, res);
} catch (FirewallCheckException e) {
    res.setStatus(405).setHeader("Allow", "GET, POST, OPTIONS");
}

When it happens

Trigger: Enabling method-check with allow-methods=[GET,POST] while the frontend issues PUT/DELETE/PATCH/OPTIONS requests; preflight OPTIONS from browsers being blocked; a lowercase 'get' in the config list.

Common situations: Enabling the method whitelist on a REST API that also needs OPTIONS for CORS preflight; forgetting DELETE when adding a delete endpoint; config lists written lowercase.

Related errors

• 非法请求：{requestPath}
• 非法请求：{requestPath}
• 非法请求头：{headerName}
• 非法请求 host：{host}
• 非法请求参数：{parameterName}

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