{"record":{"id":"8d4a1850214540d6","repo":"SonarSource/sonarqube","slug":"fail-to-initialize-servlet-filter-message","errorCode":null,"errorMessage":"Fail to initialize servlet filter: . Message: ","messagePattern":"Fail to initialize servlet filter: \\. Message: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"server/sonar-webserver/src/main/java/org/sonar/server/platform/web/MasterServletFilter.java","lineNumber":106,"sourceCode":"  public void initHttpFilters(List<HttpFilter> filterExtensions) {\n    LinkedList<HttpFilter> filterList = new LinkedList<>();\n    for (HttpFilter extension : filterExtensions) {\n      try {\n        LOG.atInfo()\n          .addArgument(extension)\n          .addArgument(() -> extension.doGetPattern().label())\n          .log(\"Initializing servlet filter {} [pattern={}]\");\n        extension.init();\n        // As for scim we need to intercept traffic to URLs with path parameters\n        // and that use is not properly handled when dealing with inclusions/exclusions of the WebServiceFilter,\n        // we need to make sure the Scim filters are invoked before the WebserviceFilter\n        if (isScimFilter(extension)) {\n          filterList.addFirst(extension);\n        } else {\n          filterList.addLast(extension);\n        }\n      } catch (Exception e) {\n        throw new IllegalStateException(\"Fail to initialize servlet filter: \" + extension + \". Message: \" + e.getMessage(), e);\n      }\n    }\n    httpFilters = filterList.toArray(new HttpFilter[0]);\n  }\n\n  private static boolean isScimFilter(HttpFilter extension) {\n    return extension.doGetPattern().getInclusions().stream()\n      .anyMatch(s -> s.startsWith(SCIM_FILTER_PATH));\n  }\n\n  @Override\n  public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws ServletException, IOException {\n    HttpServletRequest hsr = (HttpServletRequest) request;\n    if (httpFilters.length == 0) {\n      chain.doFilter(hsr, response);\n    } else {\n      String path = hsr.getRequestURI().replaceFirst(hsr.getContextPath(), \"\");\n      GodFilterChain godChain = new GodFilterChain(chain);","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver/src/main/java/org/sonar/server/platform/web/MasterServletFilter.java#L88-L124","documentation":"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.","triggerScenarios":"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().","commonSituations":"An incompatible or buggy third-party plugin whose filter initialization fails (missing dependency, wrong SonarQube API version); plugin expecting configuration that is absent.","solutions":["Identify the failing filter from the message ('Fail to initialize servlet filter: <ClassName>') and read its wrapped cause","Uninstall or upgrade the offending plugin to a version compatible with the current SonarQube server","Fix the plugin's init() code (missing config/dependency) if it is a locally developed plugin"],"exampleFix":"// before\n// plugin filter init requires sonar.auth.github.clientId, unset -> throws\n// after\nsonar.auth.github.clientId=xxx  # in sonar.properties, then restart","handlingStrategy":"try-catch","validationCode":"for (HttpFilter f : extensions) {\n  try { f.init(null); } catch (Exception e) { throw new IllegalStateException(\"Pre-flight init failed for filter \" + f.getClass().getName(), e); }\n}","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Keep plugins at versions compatible with the SonarQube server version","Read startup logs for the named failing filter class and fix its prerequisites (config, dependencies)","Test custom plugin filters in isolation before deploying"],"tags":["plugins","servlet","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}