SonarSource/sonarqube · critical · IllegalStateException

Fail to load file

Error message

Fail to load file 

What it means

WebPagesCache loads an HTML page template from disk, substitutes placeholders (context path, server status, etc.), and wraps any failure in an IllegalStateException naming the file path. It is thrown during web server startup when a bundled UI template cannot be read or processed.

Solutions

1. Verify the webapp template file exists at the reported path under the SonarQube installation
2. Check file read permissions for the user running SonarQube
3. Reinstall/repair the SonarQube distribution to restore corrupted webapp files
4. Inspect the wrapped cause in the stack trace for the real failure (e.g. officialDistribution.check())

java.nio.file.Path p = java.nio.file.Paths.get(path);
if (!java.nio.file.Files.isRegularFile(p) || !java.nio.file.Files.isReadable(p)) {
  throw new IllegalStateException("Template not readable: " + p);
}

try {
  PageBean page = pagesCache.provide(...);
} catch (IllegalStateException e) {
  LOG.error("Page template unavailable", e);
  return Response.status(503).build();
}

When it happens

Trigger: Calling loadHtmlFile with a path that does not exist or is unreadable on disk, or the template replacement steps throw (e.g. officialDistribution.check() fails). Called from provide() while wiring the web server.

Common situations: Corrupted or partial SonarQube installation where webapp files are missing; wrong SONARQUBE_HOME/web dir; file permissions; a failing distribution check throwing inside the try block.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Already started
• Can get file
• Cannot detect path of main jar file
• "Configuration file not found: " + propsFile
• ############################################################…

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

Appendix: source

Thrown at server/sonar-webserver/src/main/java/org/sonar/server/platform/web/WebPagesCache.java:102

    this.status = status;
    HTML_PATHS.forEach(path -> indexHtmlByPath.put(path, provide(path)));
  }

  private String provide(String path) {
    getClass().getResourceAsStream(INDEX_HTML_PATH);
    return loadHtmlFile(path, status.name());
  }

  private String loadHtmlFile(String path, String serverStatus) {
    try (InputStream input = servletContext.getResourceAsStream(path)) {
      String template = IOUtils.toString(requireNonNull(input), UTF_8);
      return template
        .replace(WEB_CONTEXT_PLACEHOLDER, servletContext.getContextPath())
        .replace(SERVER_STATUS_PLACEHOLDER, serverStatus)
        .replace(INSTANCE_PLACEHOLDER, WebPagesCache.SONARQUBE_INSTANCE_VALUE)
        .replace(OFFICIAL_PLACEHOLDER, String.valueOf(officialDistribution.check()));
    } catch (Exception e) {
      throw new IllegalStateException("Fail to load file " + path, e);
    }
  }
}

View on GitHub (pinned to 184c821202)