alibaba/Sentinel · error · IllegalArgumentException

Invalid HTTP status code: ${httpStatus}

Error message

Invalid HTTP status code: ${httpStatus}

What it means

WebServletConfig.setBlockPageHttpStatus(int) (classic javax.servlet web adapter) validates the HTTP status code for Sentinel's default block page and throws IllegalArgumentException for values <= 0. The value is persisted as a string in SentinelConfig under the block-page-status key. This is a startup/configuration-time guard against nonsensical status codes.

Source

Thrown at sentinel-adapter/sentinel-web-servlet/src/main/java/com/alibaba/csp/sentinel/adapter/servlet/config/WebServletConfig.java:88

                throw new IllegalArgumentException("Invalid status code: " + s);
            }
            return s;
        } catch (Exception e) {
            RecordLog.warn("[WebServletConfig] Invalid block HTTP status (" + value + "), using default 429");
            setBlockPageHttpStatus(HTTP_STATUS_TOO_MANY_REQUESTS);
        }
        return HTTP_STATUS_TOO_MANY_REQUESTS;
    }

    /**
     * Set the HTTP status of the default block page.
     *
     * @param httpStatus the HTTP status of the default block page
     * @since 1.7.0
     */
    public static void setBlockPageHttpStatus(int httpStatus) {
        if (httpStatus <= 0) {
            throw new IllegalArgumentException("Invalid HTTP status code: " + httpStatus);
        }
        SentinelConfig.setConfig(BLOCK_PAGE_HTTP_STATUS_CONF_KEY, String.valueOf(httpStatus));
    }

    private WebServletConfig() {}
}

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Set a valid status such as 429: WebServletConfig.setBlockPageHttpStatus(429) or -Dcsp.sentinel.web.block.page.status=429
2. Validate parsed values: only call the setter when code > 0
3. Check the raw property string for typos/emptiness before Integer.parseInt

Example fix

// before
int code = Integer.parseInt(cfg.get("blockPageStatus")); // may be 0
WebServletConfig.setBlockPageHttpStatus(code);

// after
int code = Integer.parseInt(cfg.getOrDefault("blockPageStatus", "429"));
WebServletConfig.setBlockPageHttpStatus(code);

if (code > 0) {
    WebServletConfig.setBlockPageHttpStatus(code);
}

When it happens

Trigger: Calling WebServletConfig.setBlockPageHttpStatus(0) or a negative int, e.g. from a -Dcsp.sentinel.web.block.page.status=0 system property or a web.xml/context param read at startup.

Common situations: System property or properties file with a missing/typo'd value parsed as 0; programmatic config in a ServletContextListener running before properties are loaded; defaulting a parse failure to 0.

Related errors

• Invalid HTTP status code: ${httpStatus}
• The sentinel_default_context can't be permit to defined!
• Bad invocation instance
• Bad invocation instance
• Bad invocation instance

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