SonarSource/sonarqube · error · IllegalStateException

"Configuration file not found: " + propsFile

Error message

"Configuration file not found: " + propsFile

What it means

The Shutdowner (SonarQube server shutdown helper) loads a Java properties configuration file passed to loadPropertiesFile. When the file at the given path does not exist (Files.isRegularFile check fails), it throws IllegalStateException("Configuration file not found: " + propsFile). This indicates the configured config path is wrong, the file was deleted, or the working directory differs from what was assumed.

Source

Thrown at sonar-shutdowner/src/main/java/org/sonar/application/Shutdowner.java:80

    }
  }

  /**
   * Loads the configuration file ${homeDir}/conf/sonar.properties.
   * An empty {@link Properties} is returned if the file does not exist.
   */
  static Properties loadPropertiesFile(File homeDir) {
    Properties p = new Properties();
    File propsFile = new File(new File(homeDir, "conf"), "sonar.properties");
    if (propsFile.exists()) {
      try (Reader reader = new InputStreamReader(new FileInputStream(propsFile), UTF_8)) {
        p.load(reader);
        return p;
      } catch (IOException e) {
        throw new IllegalStateException("Cannot open file " + propsFile, e);
      }
    } else {
      throw new IllegalStateException("Configuration file not found: " + propsFile);
    }
  }

  static File resolveTempDir(Properties p) {
    return new File(Optional.ofNullable(p.getProperty("sonar.path.temp")).orElse("temp"));
  }

  static void askForHardStop(File tmpDir) throws IOException {
    writeToShareMemory(tmpDir, 1, (byte) 0xFF);
  }

  private static void writeToShareMemory(File tmpDir, int offset, byte value) throws IOException {
    try (RandomAccessFile sharedMemory = new RandomAccessFile(new File(tmpDir, "sharedmemory"), "rw")) {
      // Using values from org.sonar.process.ProcessCommands
      MappedByteBuffer mappedByteBuffer = sharedMemory.getChannel().map(FileChannel.MapMode.READ_WRITE, 0, 50L * 10);

      // Now we are stopping all processes as quick as possible
      // by asking for stop of "app" process

View on GitHub (pinned to 184c821202)

Solutions

  1. Verify the file exists at the exact path passed in (ls <propsFile>) and fix the path.
  2. If using a relative path, run the process from the expected directory or pass an absolute path.
  3. Ensure deployment/packaging scripts actually place the properties file at that location.
  4. Check for typos or environment-specific filenames (e.g. sonar.properties vs conf/sonar.properties).

Example fix

// before
Properties p = Shutdowner.loadPropertiesFile("sonar.properties");
// after
Path props = Paths.get(System.getenv("SONAR_HOME"), "conf", "sonar.properties");
if (!Files.isRegularFile(props)) {
  throw new IllegalStateException("Check SONAR_HOME: expected config at " + props);
}
Properties p = Shutdowner.loadPropertiesFile(props);
Defensive patterns

Strategy: validation

Validate before calling

import java.nio.file.*;
if (propsFile == null || !Files.isRegularFile(propsFile)) {
  throw new IllegalArgumentException("Config file missing or not a regular file: " + propsFile);
}

Prevention

When it happens

Trigger: Calling loadPropertiesFile(path) where path does not point to an existing regular file; e.g. passing a relative path from the wrong working directory, a typo'd filename, or a path whose file was removed before startup.

Common situations: Wrong sonar home / working directory when launching the shutdowner; deployment scripts not copying conf files; running from an IDE where the working directory differs from the packaging layout; renamed or versioned config files (sonar.properties moved).

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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