dromara/Sa-Token · error · RequestPathInvalidException

非法请求：{requestPath}

Error message

非法请求：{requestPath}

What it means

The DirectoryTraversal firewall hook validates the raw request path with SaFirewallCheckHookForDirectoryTraversal.isPathValid: the path must be non-empty, start with '/', contain no '.' or '..' path components, and contain no empty components (i.e. no '//' inside or at the end). Any violation throws RequestPathInvalidException, blocking classic '../' traversal payloads before they reach your controller.

Source

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

public class SaFirewallCheckHookForDirectoryTraversal implements SaFirewallCheckHook {

    /**
     * 默认实例
     */
    public static SaFirewallCheckHookForDirectoryTraversal instance = new SaFirewallCheckHookForDirectoryTraversal();

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

    /**
     * 检查路径是否有效
     * @param path /
     * @return /
     */
    public static boolean isPathValid(String path) {
        if (path == null || path.isEmpty()) {
            return false;
        }

        // 必须以 '/' 开头
        if (path.charAt(0) != '/') {
            return false;
        }

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Fix the client/proxy to normalize the URL before sending (collapse '//' and resolve '.'/'..' segments)
2. If double slashes are legitimate for you, disable or customize the hook: SaManager.getSaFirewallStrategy().removeCheck("directory-traversal") or replace it with a tolerant implementation
3. Log the offending path in a global exception handler to find which upstream produces malformed URLs

Example fix

// before: upstream sends /static//app.js or /files/../secret
// after: normalize the path before forwarding
String normalized = req.getRequestPath().replaceAll("/+", "/");

String path = SaHolder.getRequest().getRequestPath();
if (!SaFirewallCheckHookForDirectoryTraversal.isPathValid(path)) {
    // reject / normalize before the firewall hook runs
}

try {
    chain.doFilter(req, res);
} catch (RequestPathInvalidException e) {
    res.setStatus(400);
    res.getWriter().write("malformed path");
}

When it happens

Trigger: Requests like /user/info/.., /a/./b, /static//file.css (double slash), a path not starting with '/', an empty path, or a trailing '/.' — anything where splitting on '/' yields a '.', '..' or interior empty component.

Common situations: Client SDKs or proxies appending a trailing double slash; URL builders that join segments with a duplicate '/'; attackers probing with ../etc/passwd style paths; a misconfigured gateway forwarding a path without a leading slash.

Related errors

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

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