{"record":{"id":"a8ed7ae263adf86d","repo":"SonarSource/sonarqube","slug":"failed-to-configure-root-context","errorCode":null,"errorMessage":"Failed to configure ROOT context","messagePattern":"Failed to configure ROOT context","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java","lineNumber":213,"sourceCode":"          <display-name>SonarQube Root</display-name>\n          <servlet>\n            <servlet-name>root</servlet-name>\n            <servlet-class>org.sonar.server.app.RootContextServlet</servlet-class>\n            <init-param>\n              <param-name>webContext</param-name>\n              <param-value>%s</param-value>\n            </init-param>\n          </servlet>\n          <servlet-mapping>\n            <servlet-name>root</servlet-name>\n            <url-pattern>/*</url-pattern>\n          </servlet-mapping>\n        </web-app>\"\"\".formatted(webContext);\n      FileUtils.writeStringToFile(webXmlDest, webXml, StandardCharsets.UTF_8);\n\n      addContext(tomcat, \"\", rootDir);\n    } catch (IOException e) {\n      throw new IllegalStateException(\"Failed to configure ROOT context\", e);\n    }\n  }\n\n  static class Fs {\n    void createOrCleanupDir(File dir) throws IOException {\n      FileUtils.forceMkdir(dir);\n      org.sonar.core.util.FileUtils.cleanDirectory(dir);\n    }\n  }\n}\n","sourceCodeStart":195,"sourceCodeEnd":224,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java#L195-L224","documentation":"TomcatContexts.addRootContext sets up the ROOT context ('/'), generating a web.xml from a template and writing it to disk before delegating to addContext. If any of those steps throws IOException (writing the generated web.xml, creating the root directory), it is wrapped in an IllegalStateException with this message.","triggerScenarios":"IOException while FileUtils.writeStringToFile writes the generated web.xml to the temporary root dir, or while creating/cleaning the ROOT directory, during server startup (called from configure).","commonSituations":"Unwritable temp/work directory; filesystem permission problems on the installation dir; disk full; a file occupying the path where webXmlDest should be written.","solutions":["Ensure the working/temp directories used by Tomcat are writable by the sonar process user","Check disk space and remove a blocking file at the webXmlDest path","Run as the correct user with write access to $SONARQUBE_HOME"],"exampleFix":"// before\nchmod 555 /opt/sonarqube  # web.xml can't be written\n// after\nchown -R sonar:sonar /opt/sonarqube  # allow writes to temp/context dirs","handlingStrategy":"try-catch","validationCode":"File rootDir = ...; File webXmlDest = new File(rootDir, \"WEB-INF/web.xml\");\nif (!rootDir.getParentFile().canWrite()) throw new IllegalStateException(\"Cannot write generated web.xml, no write access to \" + rootDir.getParentFile());","typeGuard":null,"tryCatchPattern":"try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().equals(\"Failed to configure ROOT context\")) { log.error(\"Check write access to install dir and disk space\", e.getCause()); } throw e; }","preventionTips":["Grant the sonar user write access to $SONARQUBE_HOME and its temp dirs","Monitor disk space on the server volume","Remove stale files blocking WEB-INF/web.xml after failed startups"],"tags":["tomcat","startup","filesystem"],"backgroundTag":"file-write-failed","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"}