dromara/Sa-Token · error · FirewallCheckException

非法请求头：{headerName}

Error message

非法请求头：{headerName}

What it means

The Header firewall hook iterates the configured notAllowHeaderNames list and throws FirewallCheckException if the incoming request carries any of those headers, regardless of value. It is an anti-smuggling/header-injection control — typical defaults block headers that proxies or frameworks treat specially. The message names the exact header that triggered the block.

Source

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

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

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

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Remove the offending header from the client request (the error message tells you exactly which one)
2. If the header is unavoidable, delete it from sa-token.firewall.not-allow-header-names in your config
3. Configure your reverse proxy (nginx/envoy) to strip the header before proxy_pass reaches the app

Example fix

# before: client sends a blocked header
curl -H "X-Forwarded-For: 1.2.3.4" http://app/api

# after
sa-token:
  firewall:
    not-allow-header-names: []   # or drop the header from the client

Set<String> denied = new HashSet<>(
    SaManager.getConfig().getFirewall().getNotAllowHeaderNames());
for (String name : Collections.list(req.getHeaderNames())) {
    if (denied.contains(name)) {
        // strip or reject before sa-token firewall runs
    }
}

try {
    chain.doFilter(req, res);
} catch (FirewallCheckException e) {
    res.setStatus(400);
    // message contains the blocked header name — log, don't return it
}

When it happens

Trigger: Any request containing a header listed in sa-token.firewall.not-allow-header-names (defaults include X-Forwarded-For style hop-by-hop headers depending on version), e.g. a client sending 'Connection: keep-aliveUpgrade' or 'Transfer-Encoding: chunked'.

Common situations: Corporate proxies or CDNs injecting blocked headers into every request; curl scripts copied from docs that set a forbidden header; upgrading sa-token versions where the default deny-list grew and now blocks a header your client legitimately sends.

Related errors

• 非法请求：{requestPath}
• 非法请求：{requestPath}
• 非法请求 host：{host}
• 非法请求 Method：{method}
• 非法请求参数：{parameterName}

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