dromara/Sa-Token · error · RequestPathInvalidException

请求 path 包含禁止字符：{requestPath}

Error message

请求 path 包含禁止字符：{requestPath}

What it means

The PathBannedCharacter firewall hook runs SaFoxUtil.hasNonPrintableASCII on the raw request path and throws RequestPathInvalidException if any non-printable ASCII character (control characters, etc.) is present. This blocks control-character injection into paths, which some proxies and log systems mishandle. It is one of two checks in the same hook; the other (message with '%') covers percent signs.

Source

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

     * @param bannedPercentage 是否严格禁止出现百分号字符 % （默认：否）
     */
    public void resetConfig(boolean bannedPercentage) {
        this.bannedPercentage = bannedPercentage;
    }

    /**
     * 执行的方法
     *
     * @param req 请求对象
     * @param res 响应对象
     * @param extArg 预留扩展参数
     */
    @Override
    public void execute(SaRequest req, SaResponse res, Object extArg) {
        // 非可打印 ASCII 字符检查
        String requestPath = req.getRequestPath();
        if(SaFoxUtil.hasNonPrintableASCII(requestPath)) {
            throw new RequestPathInvalidException("请求 path 包含禁止字符：" + requestPath, requestPath);
        }
        if(bannedPercentage && requestPath.contains("%")) {
            throw new RequestPathInvalidException("请求 path 包含禁止字符 %：" + requestPath, requestPath);
        }
    }

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Reject/fix the client that produces paths with control characters — URL-encode such data instead
2. If a front proxy decodes percent-escapes too early, configure it to pass the path through encoded
3. Treat occurrences as security events: these paths are almost never legitimate traffic

Example fix

// before
String path = "/files/a" + (char)0 + ".txt"; // non-printable in path

// after
String path = "/files/a%00.txt"; // kept percent-encoded on the wire

String path = SaHolder.getRequest().getRequestPath();
if (SaFoxUtil.hasNonPrintableASCII(path)) {
    // reject with 400; never normalize control chars into the path
}

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

When it happens

Trigger: A request path containing control chars such as \x00-\x1F, \x7F, or other non-printable bytes — e.g. curl with a raw newline or null byte in the URL, or an encoded %0A that was decoded before the check runs.

Common situations: Attackers probing with null-byte or CRLF injection in URLs; buggy clients that embed unescaped newline/tab into paths; a gateway that percent-decodes the path before forwarding so %0d%0a becomes literal CR LF.

Related errors

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

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