dromara/Sa-Token · error · RequestPathInvalidException

非法请求：{requestPath}

Error message

非法请求：{requestPath}

What it means

The PathDangerCharacter firewall hook checks whether the raw request path contains any substring from the configured dangerCharacter list (defaults include characters like < > \" ' and SQL/XSS-ish fragments depending on version). A containment match throws RequestPathInvalidException. This blocks script/SQL fragments from reaching controllers via the URL.

Source

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

     * @param character 危险字符列表
     */
    public void resetConfig(String... character) {
        this.dangerCharacter = Arrays.asList(character);
    }

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

}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Move free-text input from the path into a query parameter or POST body (query values and bodies are not checked by this hook)
2. URL-encode user input before building the path, or trim/reject dangerous characters client-side
3. Customize the list via sa-token.firewall.danger-character if a character is required by your scheme

Example fix

// before: free text in path segment
@GetMapping("/search/{keyword}")  // /search/it's -> blocked

// after: free text as query param
@GetMapping("/search")  // /search?keyword=it's -> passes

String path = SaHolder.getRequest().getRequestPath();
for (String d : SaManager.getConfig().getFirewall().getDangerCharacter()) {
    if (path.contains(d)) { /* reject 400 / move input to query param */ }
}

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

When it happens

Trigger: Paths containing any configured danger string, e.g. /search/<script>, /q/it's, /find/a=b -- or any path where a path-variable naturally contains a quote or angle bracket.

Common situations: REST APIs that put free-text search terms in the path segment (e.g. /search/{keyword}) and users type quotes or <; documentation URLs containing angle brackets; attack probes with <script> or ' OR 1=1.

Related errors

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

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