SonarSource/sonarqube · critical · IllegalStateException

Fail to configure webapp from

Error message

Fail to configure webapp from

What it means

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.

Source

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

      context.setClearReferencesStopThreads(false);
      context.setClearReferencesStopTimerThreads(false);
      context.setClearReferencesStopTimerThreads(false);
      context.setAntiResourceLocking(false);
      context.setReloadable(false);
      context.setUseHttpOnly(true);
      context.setTldValidation(false);
      context.setXmlValidation(false);
      context.setXmlNamespaceAware(false);
      context.setUseNaming(false);
      context.setDelegate(true);
      context.setJarScanner(new NullJarScanner());
      context.setAllowCasualMultipartParsing(true);
      context.setCookies(false);
      // disable JSP and WebSocket support
      context.setContainerSciFilter("org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer");
      return context;
    } catch (Exception e) {
      throw new IllegalStateException("Fail to configure webapp from " + dir, e);
    }
  }

  private static File webappDir(Props props) {
    return new File(props.value(PATH_HOME.getKey()), "web");
  }

  private static void configureDeployErrorPages(File dir, String contextPath) throws IOException {
    // Create a simple web.xml with error page configuration that redirects to main webapp
    File webInfDir = new File(dir, "WEB-INF");
    FileUtils.forceMkdir(webInfDir);

    // Create a redirect HTML page that immediately redirects to the main context
    File errorHtmlFile = new File(dir, "error.html");
    String mainContextUrl = contextPath.replace("/deploy", "/not-found-deploy");

    String errorHtml = """
      <!DOCTYPE html>

View on GitHub (pinned to 184c821202)

Solutions

  1. Verify the 'web' directory exists under $SONARQUBE_HOME and is readable by the process user
  2. Reinstall/re-extract the SonarQube distribution to restore missing web assets
  3. Check the wrapped cause (e.getCause()) for the underlying Tomcat configuration error and fix it specifically

Example fix

// before
ls $SONAR_HOME  # web/ missing after bad extraction
// after
unzip -o sonarqube-*.zip -d /opt/ && ls /opt/sonarqube-*/web  # web/ present
Defensive patterns

Strategy: validation

Validate before calling

File web = new File(props.value("sonar.path.home"), "web");
if (!web.isDirectory() || !web.canRead()) throw new IllegalStateException("Webapp directory missing or unreadable: " + web);

Try / catch

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

Prevention

When it happens

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

Common situations: Corrupted or partially extracted SonarQube installation where the 'web' directory is missing; wrong sonar.path.home resolution; packaging a custom build without web assets.

Related errors

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