SonarSource/sonarqube · error · IllegalStateException

Fail to initialize servlet filter: . Message:

Error message

Fail to initialize servlet filter: . Message: 

What it means

MasterServletFilter.initHttpFilters initializes the list of HttpFilter extensions (plugin-provided servlet filters). If any individual extension filter throws during its own init, the exception is wrapped in an IllegalStateException naming the failing filter class and its message, failing the servlet filter startup.

Solutions

1. Identify the failing filter from the message ('Fail to initialize servlet filter: <ClassName>') and read its wrapped cause
2. Uninstall or upgrade the offending plugin to a version compatible with the current SonarQube server
3. Fix the plugin's init() code (missing config/dependency) if it is a locally developed plugin

Example fix

// before
// plugin filter init requires sonar.auth.github.clientId, unset -> throws
// after
sonar.auth.github.clientId=xxx  # in sonar.properties, then restart

for (HttpFilter f : extensions) {
  try { f.init(null); } catch (Exception e) { throw new IllegalStateException("Pre-flight init failed for filter " + f.getClass().getName(), e); }
}

try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Fail to initialize servlet filter: ")) { String failing = e.getMessage().split(": ")[1]; log.error("Remove or upgrade plugin providing filter " + failing, e.getCause()); } throw e; }

When it happens

Trigger: A plugin-provided WebService/HttpFilter extension throws an exception in its init() or constructor when the web server starts; initHttpFilters is called from init() and start().

Common situations: An incompatible or buggy third-party plugin whose filter initialization fails (missing dependency, wrong SonarQube API version); plugin expecting configuration that is absent.

Related errors

• Servlet filter is already instantiated
• A plugin is storing excessively large data in the following…
• Configuration error: property definition named
• ############################################################…
• Fail to instantiate class

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/8d4a1850214540d6. Report an issue: GitHub.

Appendix: source

Thrown at server/sonar-webserver/src/main/java/org/sonar/server/platform/web/MasterServletFilter.java:106

  public void initHttpFilters(List<HttpFilter> filterExtensions) {
    LinkedList<HttpFilter> filterList = new LinkedList<>();
    for (HttpFilter extension : filterExtensions) {
      try {
        LOG.atInfo()
          .addArgument(extension)
          .addArgument(() -> extension.doGetPattern().label())
          .log("Initializing servlet filter {} [pattern={}]");
        extension.init();
        // As for scim we need to intercept traffic to URLs with path parameters
        // and that use is not properly handled when dealing with inclusions/exclusions of the WebServiceFilter,
        // we need to make sure the Scim filters are invoked before the WebserviceFilter
        if (isScimFilter(extension)) {
          filterList.addFirst(extension);
        } else {
          filterList.addLast(extension);
        }
      } catch (Exception e) {
        throw new IllegalStateException("Fail to initialize servlet filter: " + extension + ". Message: " + e.getMessage(), e);
      }
    }
    httpFilters = filterList.toArray(new HttpFilter[0]);
  }

  private static boolean isScimFilter(HttpFilter extension) {
    return extension.doGetPattern().getInclusions().stream()
      .anyMatch(s -> s.startsWith(SCIM_FILTER_PATH));
  }

  @Override
  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws ServletException, IOException {
    HttpServletRequest hsr = (HttpServletRequest) request;
    if (httpFilters.length == 0) {
      chain.doFilter(hsr, response);
    } else {
      String path = hsr.getRequestURI().replaceFirst(hsr.getContextPath(), "");
      GodFilterChain godChain = new GodFilterChain(chain);

View on GitHub (pinned to 184c821202)