SonarSource/sonarqube · error · MessageException

JVM option '%s' must be set to '%s'. Got '%s'

Error message

JVM option '%s' must be set to '%s'. Got '%s'

What it means

checkRequiredJavaOptions validates that required JVM system properties have exact expected values. A MessageException is thrown naming the property, the expected value, and the actual value when they mismatch.

Source

Thrown at server/sonar-process/src/main/java/org/sonar/process/MinimumViableSystem.java:55

    checkWritableDir(System.getProperty("java.io.tmpdir"));
    return this;
  }

  // Visible for testing
  void checkWritableDir(String tempPath) {
    try {
      File tempFile = File.createTempFile("check", "tmp", new File(tempPath));
      deleteQuietly(tempFile);
    } catch (IOException e) {
      throw new IllegalStateException(format("Temp directory is not writable: %s", tempPath), e);
    }
  }

  public MinimumViableSystem checkRequiredJavaOptions(Map<String, String> requiredJavaOptions) {
    for (Map.Entry<String, String> entry : requiredJavaOptions.entrySet()) {
      String value = System.getProperty(entry.getKey());
      if (!CS.equals(value, entry.getValue())) {
        throw new MessageException(format(
          "JVM option '%s' must be set to '%s'. Got '%s'", entry.getKey(), entry.getValue(), StringUtils.defaultString(value)));
      }
    }
    return this;
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Start the process with the required -D JVM options exactly as documented
2. Verify with `jinfo`/`jcmd` or a debug print that System.getProperty(key) matches the expected value
3. Fix the launcher script that drops the flags

Example fix

// before
java -jar sonar-application.jar
// after
java -Dprocess.index=1 -Dprocess.key=web -Djava.io.tmpdir=/tmp/sonar -jar sonar-application.jar

for (Map.Entry<String,String> e : required.entrySet()) {
  if (!e.getValue().equals(System.getProperty(e.getKey()))) {
    throw new IllegalStateException("JVM option " + e.getKey() + " must be " + e.getValue());
  }
}

try { mvs.checkRequiredJavaOptions(required); } catch (MessageException e) { LOGGER.error(e.getMessage()); throw e; }

When it happens

Trigger: Starting a SonarQube process without the required JVM options (e.g. process-specific -D properties), or with values altered by wrappers/scripts.

Common situations: Launching a child process manually without the standard startup scripts; custom launcher dropping -D flags; conflicting JVM configs between versions.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Property '%s' is not valid, not a directory: %s
• Fail to launch process [%s]
• HTTP port %s is invalid
• Fail to generate secret key
• Worker count '%s' is invalid. It must be an integer strictly

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