alibaba/Sentinel · error · IllegalStateException

${path}

Error message

${path}

What it means

FilterUtil.normalizePath (sentinel-web-servlet) normalizes the request path (resolving '.' and '..' segments). When the path is absolute and a '..' segment would backtrack above the root (level == 0), it throws IllegalStateException whose message is the raw offending path. This guards the servlet filter against path-traversal-style URLs whose normalized form cannot be represented as an absolute path.

Source

Thrown at sentinel-adapter/sentinel-web-servlet/src/main/java/com/alibaba/csp/sentinel/adapter/servlet/util/FilterUtil.java:143

            if (index == length) {
                break;
            }

            int nextSlashIndex = indexOfSlash(pathChars, index, true);

            String element = new String(pathChars, index, nextSlashIndex - index);
            index = nextSlashIndex;

            // Ignore "."
            if (".".equals(element)) {
                continue;
            }

            // Backtrack ".."
            if ("..".equals(element)) {
                if (level == 0) {
                    if (isAbsolutePath) {
                        throw new IllegalStateException(path);
                    } else {
                        buf.append("..").append(PATH_SPLIT);
                    }
                } else {
                    buf.setLength(pathChars[--level]);
                }

                continue;
            }

            pathChars[level++] = (char)buf.length();
            buf.append(element).append(PATH_SPLIT);
        }

        // remove the last "/"
        if (buf.length() > 0) {
            if (!endsWithSlash || removeTrailingSlash) {
                buf.setLength(buf.length() - 1);

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Reject/sanitize such requests upstream (e.g. a front proxy or earlier filter that normalizes or blocks '..' segments)
2. Wrap the filter chain with a try/catch for IllegalStateException and return 400 for malformed paths
3. Upgrade the servlet adapter — later Sentinel versions changed path handling; check the changelog for FilterUtil fixes
4. If it comes from tests, feed normalized absolute paths without leading '..' overflow

Example fix

// before
chain.doFilter(request, response); // traversal path reaches FilterUtil

// after
String path = request.getPathInfo() != null ? request.getPathInfo() : request.getServletPath();
if (path.contains("..")) {
    response.sendError(HttpServletResponse.SC_BAD_REQUEST);
    return;
}
chain.doFilter(request, response);

String p = request.getServletPath() + (request.getPathInfo() == null ? "" : request.getPathInfo());
// count leading-depth vs '..' segments before the filter processes it
boolean tooManyParent = false; int depth = 0;
for (String seg : p.split("/")) {
    if ("..".equals(seg)) { if (depth == 0) { tooManyParent = true; break; } depth--; }
    else if (!seg.isEmpty() && !".".equals(seg)) depth++;
}
if (tooManyParent) { /* reject 400 */ }

try {
    chain.doFilter(request, response);
} catch (IllegalStateException e) {
    response.sendError(HttpServletResponse.SC_BAD_REQUEST);
}

When it happens

Trigger: An incoming HTTP request whose servletPath/pathInfo, treated as an absolute path, contains more '..' segments than preceding levels, e.g. '/../../etc/passwd' or '/a/../../..'; the exception is thrown inside getResourcePath/normalizeAbsolutePath during CommonFilter processing.

Common situations: Security scanners or penetration tests sending traversal sequences; misbehaving clients or proxies sending unnormalized URLs; tests that feed raw traversal paths to FilterUtil.filterTarget.

Related errors

• Publisher type is not supported: ${canonicalName}
• Invalid HTTP status code: ${httpStatus}
• Invalid HTTP status code: ${httpStatus}
• Bad async context state, expected entry: %s, but actual: %s
• arrayAdd() is unavailable if countAndSum() has been called

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/a3aadece9fb43cd1. Report an issue: GitHub.