{"record":{"id":"5d69020e543f2c8c","repo":"SonarSource/sonarqube","slug":"fail-to-configure-webapp-from","errorCode":null,"errorMessage":"Fail to configure webapp from ","messagePattern":"Fail to configure webapp from ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java","lineNumber":122,"sourceCode":" context.setClearReferencesStopThreads(false);\n context.setClearReferencesStopTimerThreads(false);\n context.setClearReferencesStopTimerThreads(false);\n context.setAntiResourceLocking(false);\n context.setReloadable(false);\n context.setUseHttpOnly(true);\n context.setTldValidation(false);\n context.setXmlValidation(false);\n context.setXmlNamespaceAware(false);\n context.setUseNaming(false);\n context.setDelegate(true);\n context.setJarScanner(new NullJarScanner());\n context.setAllowCasualMultipartParsing(true);\n context.setCookies(false);\n // disable JSP and WebSocket support\n context.setContainerSciFilter(\"org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer\");\n return context;\n } catch (Exception e) {\n throw new IllegalStateException(\"Fail to configure webapp from \" + dir, e);\n }\n }\n\n private static File webappDir(Props props) {\n return new File(props.value(PATH_HOME.getKey()), \"web\");\n }\n\n private static void configureDeployErrorPages(File dir, String contextPath) throws IOException {\n // Create a simple web.xml with error page configuration that redirects to main webapp\n File webInfDir = new File(dir, \"WEB-INF\");\n FileUtils.forceMkdir(webInfDir);\n\n // Create a redirect HTML page that immediately redirects to the main context\n File errorHtmlFile = new File(dir, \"error.html\");\n String mainContextUrl = contextPath.replace(\"/deploy\", \"/not-found-deploy\");\n\n String errorHtml = \"\"\"\n ","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java#L104-L140","documentation":"TomcatContexts.addContext builds a Tomcat StandardContext for a webapp directory (docBase, JSP/WebSocket disabled, etc.). Any exception while configuring the webapp from that directory is wrapped in an IllegalStateException with this message, aborting startup of the web server context.","triggerScenarios":"The webapp directory ($SONARQUBE_HOME/web) is missing, unreadable, or invalid as a docBase so Tomcat's context configuration throws; addContext is called from webapp(), addStaticDir() and addRootContext().","commonSituations":"Corrupted or partially extracted SonarQube installation where the 'web' directory is missing; wrong sonar.path.home resolution; packaging a custom build without web assets.","solutions":["Verify the 'web' directory exists under $SONARQUBE_HOME and is readable by the process user","Reinstall/re-extract the SonarQube distribution to restore missing web assets","Check the wrapped cause (e.getCause()) for the underlying Tomcat configuration error and fix it specifically"],"exampleFix":"// before\nls $SONAR_HOME # web/ missing after bad extraction\n// after\nunzip -o sonarqube-*.zip -d /opt/ && ls /opt/sonarqube-*/web # web/ present","handlingStrategy":"validation","validationCode":"File web = new File(props.value(\"sonar.path.home\"), \"web\");\nif (!web.isDirectory() || !web.canRead()) throw new IllegalStateException(\"Webapp directory missing or unreadable: \" + web);","typeGuard":null,"tryCatchPattern":"try { contexts.configure(tomcat); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"Fail to configure webapp from\")) { log.error(\"Verify the SonarQube distribution is fully extracted (web/ dir present)\"); } throw e; }","preventionTips":["Verify archive checksum and complete extraction after installing/upgrading SonarQube","Keep sonar.path.home correct when running from custom launchers","Reinstall the distribution if the 'web' directory is damaged"],"tags":["tomcat","startup","deployment"],"backgroundTag":"directory-not-found","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}