SonarSource/sonarqube · error · MessageException

a JVM option can't overwrite mandatory JVM options. The foll

Error message

a JVM option can't overwrite mandatory JVM options. The following JVM options defined by property '%s' are invalid: %s

What it means

JvmOptions.checkMandatoryOptionOverwrite (list variant) rejects user-provided JVM options that collide with options SonarQube sets mandatorily for a child process. If any property-sourced option would overwrite a mandatory key (e.g. a user -Xms/-Xmx conflicting with reserved ES options), a MessageException lists each 'option overwrites mandatory' pair.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/command/JvmOptions.java:99

    List<String> invalidOptions = jvmOptionsFromProperty.stream()
      .filter(JvmOptions::isInvalidOption)
      .toList();
    if (!invalidOptions.isEmpty()) {
      throw new MessageException(format(
        "a JVM option can't be empty and must start with '-'. The following JVM options defined by property '%s' are invalid: %s",
        propertyName,
        invalidOptions.stream()
          .collect(joining(", "))));
    }
  }

  private void checkMandatoryOptionOverwrite(String propertyName, List<String> jvmOptionsFromProperty) {
    List<Match> matches = jvmOptionsFromProperty.stream()
      .map(jvmOption -> new Match(jvmOption, mandatoryOptionFor(jvmOption)))
      .filter(match -> match.mandatoryOption() != null)
      .toList();
    if (!matches.isEmpty()) {
      throw new MessageException(format(
        "a JVM option can't overwrite mandatory JVM options. The following JVM options defined by property '%s' are invalid: %s",
        propertyName,
        matches.stream()
          .map(m -> m.option() + " overwrites " + m.mandatoryOption.getKey() + m.mandatoryOption.getValue())
          .collect(joining(", "))));
    }
  }

  /**
   * Add an option.
   * Argument is trimmed before being added.
   *
   * @throws IllegalArgumentException if argument is empty or does not start with {@code -}.
   */
  public T add(String str) {
    requireNonNull(str, JVM_OPTION_NOT_NULL_ERROR_MESSAGE);
    String value = str.trim();
    if (isInvalidOption(value)) {

View on GitHub (pinned to 184c821202)

Solutions

  1. Remove the conflicting option from the javaOpts property
  2. Use the dedicated SonarQube property for that setting instead (e.g. sonar.search.javaOpts → sonar.search.javaOpts restrictions or the dedicated heap properties)
  3. Review the error message: each 'X overwrites Y' pair tells you exactly which user option collides with which mandatory option
  4. After upgrading SonarQube, re-audit javaOpts properties against the new mandatory option list

Example fix

// before
sonar.search.javaOpts=-Xms4G -Xmx4G  (overwrites managed heap)
// after
sonar.search.javaHeapSize=4096
sonar.search.javaOpts=-XX:+UseG1GC
Defensive patterns

Strategy: validation

Validate before calling

Set<String> reserved = Set.of("-Xms", "-Xmx", "-XX:+HeapDumpOnOutOfMemoryError"); // per-process mandatory set
boolean conflicts = List.of(javaOptsProperty.split("\\s+")).stream()
  .anyMatch(o -> reserved.stream().anyMatch(r -> o.startsWith(r)));

Try / catch

try {
  launcher.start();
} catch (MessageException e) {
  if (e.getMessage().contains("can't overwrite mandatory JVM options")) {
    log.error("Remove options that collide with mandatory JVM options", e);
  }
}

Prevention

When it happens

Trigger: Setting a JVM options property (sonar.web.javaOpts, sonar.ce.javaOpts, sonar.search.javaOpts) with an option whose key matches a mandatory option for that process — for example providing sonar.search.javaOpts values that conflict with options SonarQube force-sets for Elasticsearch (like -Xms/-Xmx managed via sonar.search.javaOpts restrictions or heap settings).

Common situations: Users trying to tune heap size for Elasticsearch directly in javaOpts while SonarQube manages it via sonar.search.javaHeapXxx properties, or migrating old configs that manually set options now reserved by newer SonarQube versions.

Related errors

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