{"record":{"id":"8ad0c226b74f3faf","repo":"dromara/Sa-Token","slug":"headername","errorCode":null,"errorMessage":"非法请求头：{headerName}","messagePattern":"非法请求头：(.+?)","errorType":"exception","errorClass":"FirewallCheckException","httpStatus":null,"severity":"error","filePath":"sa-token-core/src/main/java/cn/dev33/satoken/strategy/hooks/SaFirewallCheckHookForHeader.java","lineNumber":67,"sourceCode":"     * @param notAllowHeaderNames 不允许的请求头列表 (先清空原来的，再添加上新的)\n     */\n    public void resetConfig(String... notAllowHeaderNames) {\n        this.notAllowHeaderNames.clear();\n        this.notAllowHeaderNames.addAll(Arrays.asList(notAllowHeaderNames));\n    }\n\n    /**\n     * 执行的方法\n     *\n     * @param req 请求对象\n     * @param res 响应对象\n     * @param extArg 预留扩展参数\n     */\n    @Override\n    public void execute(SaRequest req, SaResponse res, Object extArg) {\n        for (String headerName : notAllowHeaderNames) {\n            if(req.getHeader(headerName) != null) {\n                throw new FirewallCheckException(\"非法请求头：\" + headerName);\n            }\n        }\n    }\n\n}\n","sourceCodeStart":49,"sourceCodeEnd":73,"githubUrl":"https://github.com/dromara/Sa-Token/blob/ac2c7f6e94a78573cf0bcb932dd8b04e68fad189/sa-token-core/src/main/java/cn/dev33/satoken/strategy/hooks/SaFirewallCheckHookForHeader.java#L49-L73","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Remove the offending header from the client request (the error message tells you exactly which one)","If the header is unavoidable, delete it from sa-token.firewall.not-allow-header-names in your config","Configure your reverse proxy (nginx/envoy) to strip the header before proxy_pass reaches the app"],"exampleFix":"# before: client sends a blocked header\ncurl -H \"X-Forwarded-For: 1.2.3.4\" http://app/api\n\n# after\nsa-token:\n  firewall:\n    not-allow-header-names: []   # or drop the header from the client","handlingStrategy":"validation","validationCode":"Set<String> denied = new HashSet<>(\n    SaManager.getConfig().getFirewall().getNotAllowHeaderNames());\nfor (String name : Collections.list(req.getHeaderNames())) {\n    if (denied.contains(name)) {\n        // strip or reject before sa-token firewall runs\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    chain.doFilter(req, res);\n} catch (FirewallCheckException e) {\n    res.setStatus(400);\n    // message contains the blocked header name — log, don't return it\n}","preventionTips":["Have proxies strip hop-by-hop headers before forwarding to the app","Document the deny-list for frontend teams so they never set those headers","Re-check the default deny-list after upgrading sa-token"],"tags":["sa-token","firewall","security","http-headers"],"backgroundTag":null,"analyzedSha":"ac2c7f6e94a78573cf0bcb932dd8b04e68fad189","analyzedAt":"2026-08-14T14:36:10.271Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}