dromara/Sa-Token · error · FirewallCheckException

非法请求参数：{parameterName}

Error message

非法请求参数：{parameterName}

What it means

The Parameter firewall hook iterates the configured notAllowParameterNames list and throws FirewallCheckException if the request contains any of those query/form parameters with a non-null value (mere presence is enough; the value itself is irrelevant). It is used to reject parameter smuggling of fields the framework treats specially, such as satoken token-submission parameters.

Source

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

     * @param notAllowParameterNames 不允许的请求参数列表 (先清空原来的，再添加上新的)
     */
    public void resetConfig(String... notAllowParameterNames) {
        this.notAllowParameterNames.clear();
        this.notAllowParameterNames.addAll(Arrays.asList(notAllowParameterNames));
    }

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

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Stop sending the blocked parameter — submit the token via header (satoken: xxx) or cookie instead of query string
2. Remove the parameter name from sa-token.firewall.not-allow-parameter-names if it is legitimately required
3. For third-party callbacks, remap the parameter on your gateway before it reaches the app

Example fix

// before: token passed as query parameter (blocked)
fetch('/api/user?satoken=' + token);

// after: token passed via header
fetch('/api/user', { headers: { satoken: token } });

Set<String> denied = new HashSet<>(
    SaManager.getConfig().getFirewall().getNotAllowParameterNames());
for (String p : denied) {
    if (req.getParam(p) != null) { /* strip/reject before firewall */ }
}

try {
    chain.doFilter(req, res);
} catch (FirewallCheckException e) {
    res.setStatus(400);
}

When it happens

Trigger: A GET/POST request carrying a query or form parameter whose name appears in sa-token.firewall.not-allow-parameter-names — most commonly 'satoken' when the app submits the token via query string while the parameter deny-list blocks it.

Common situations: Frontend appending the token as ?satoken=xxx on image/file downloads while the firewall blocks that parameter; a third-party callback (OAuth, payment notify) sending a blocked parameter name; versions whose default deny-list includes parameters your integration now uses.

Related errors

• 非法请求：{requestPath}
• 非法请求：{requestPath}
• 非法请求头：{headerName}
• 非法请求 host：{host}
• 非法请求 Method：{method}

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