SonarSource/sonarqube · critical · IllegalStateException

Failed to configure ROOT context

Error message

Failed to configure ROOT context

What it means

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.

Source

Thrown at server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java:213

          <display-name>SonarQube Root</display-name>
          <servlet>
            <servlet-name>root</servlet-name>
            <servlet-class>org.sonar.server.app.RootContextServlet</servlet-class>
            <init-param>
              <param-name>webContext</param-name>
              <param-value>%s</param-value>
            </init-param>
          </servlet>
          <servlet-mapping>
            <servlet-name>root</servlet-name>
            <url-pattern>/*</url-pattern>
          </servlet-mapping>
        </web-app>""".formatted(webContext);
      FileUtils.writeStringToFile(webXmlDest, webXml, StandardCharsets.UTF_8);

      addContext(tomcat, "", rootDir);
    } catch (IOException e) {
      throw new IllegalStateException("Failed to configure ROOT context", e);
    }
  }

  static class Fs {
    void createOrCleanupDir(File dir) throws IOException {
      FileUtils.forceMkdir(dir);
      org.sonar.core.util.FileUtils.cleanDirectory(dir);
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Ensure the working/temp directories used by Tomcat are writable by the sonar process user
2. Check disk space and remove a blocking file at the webXmlDest path
3. Run as the correct user with write access to $SONARQUBE_HOME

Example fix

// before
chmod 555 /opt/sonarqube  # web.xml can't be written
// after
chown -R sonar:sonar /opt/sonarqube  # allow writes to temp/context dirs

File rootDir = ...; File webXmlDest = new File(rootDir, "WEB-INF/web.xml");
if (!rootDir.getParentFile().canWrite()) throw new IllegalStateException("Cannot write generated web.xml, no write access to " + rootDir.getParentFile());

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; }

When it happens

Trigger: 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).

Common situations: Unwritable temp/work directory; filesystem permission problems on the installation dir; disk full; a file occupying the path where webXmlDest should be written.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Property '%s' is not valid, not a directory: %s
• Fail to create or clean-up directory %s
• Fail to configure webapp from
• Can not write to file
• Can not delete

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