{"record":{"id":"d77dc675875aae6b","repo":"SonarSource/sonarqube","slug":"a-jvm-option-can-t-overwrite-mandatory-jvm-options-d77dc6","errorCode":null,"errorMessage":"a JVM option can't overwrite mandatory JVM options. %s overwrites %s","messagePattern":"a JVM option can't overwrite mandatory JVM options\\. (.+?) overwrites (.+?)","errorType":"validation","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"server/sonar-main/src/main/java/org/sonar/application/command/JvmOptions.java","lineNumber":129,"sourceCode":"   *\n   * @throws IllegalArgumentException if argument is empty or does not start with {@code -}.\n   */\n  public T add(String str) {\n    requireNonNull(str, JVM_OPTION_NOT_NULL_ERROR_MESSAGE);\n    String value = str.trim();\n    if (isInvalidOption(value)) {\n      throw new IllegalArgumentException(\"a JVM option can't be empty and must start with '-'\");\n    }\n    checkMandatoryOptionOverwrite(value);\n    options.add(value);\n\n    return castThis();\n  }\n\n  private void checkMandatoryOptionOverwrite(String value) {\n    Map.Entry<String, String> overriddenMandatoryOption = mandatoryOptionFor(value);\n    if (overriddenMandatoryOption != null) {\n      throw new MessageException(String.format(\n        \"a JVM option can't overwrite mandatory JVM options. %s overwrites %s\",\n        value,\n        overriddenMandatoryOption.getKey() + overriddenMandatoryOption.getValue()));\n    }\n  }\n\n  @CheckForNull\n  private Map.Entry<String, String> mandatoryOptionFor(String jvmOption) {\n    return mandatoryOptions.entrySet().stream()\n      .filter(s -> jvmOption.startsWith(s.getKey()) && !jvmOption.equals(s.getKey() + s.getValue()))\n      .findFirst()\n      .orElse(null);\n  }\n\n  private static boolean isInvalidOption(String value) {\n    return value.isEmpty() || !value.startsWith(\"-\");\n  }\n","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-main/src/main/java/org/sonar/application/command/JvmOptions.java#L111-L147","documentation":"The single-value variant of checkMandatoryOptionOverwrite validates one user-supplied JVM option and throws a MessageException if it would overwrite a mandatory option SonarQube force-sets on the child JVM. The message names both the offending value and the mandatory option (key+value) it would replace.","triggerScenarios":"Calling addFromMandatoryProperty with a single JVM option string whose key matches a reserved mandatory option, e.g. passing -Xmx or -Xms where the process heap is managed by SonarQube itself.","commonSituations":"Hand-tuning child process heap or GC flags that newer SonarQube versions reserve, applying the same javaOpts template to all processes when one process has that option reserved.","solutions":["Delete the colliding option from the user JVM options property","Let SonarQube control that setting through its dedicated property (e.g. heap-size properties for Elasticsearch)","Read 'X overwrites Y' in the message to see the reserved option (Y) and remove user option (X)","Re-check the property after SonarQube upgrades, as the set of mandatory options can grow"],"exampleFix":"// before\nsonar.web.javaOpts=-Xmx1024m -Xms512m\n// after (non-reserved flags only)\nsonar.web.javaOpts=-XX:+HeapDumpOnOutOfMemoryError","handlingStrategy":"validation","validationCode":"boolean conflictsWithMandatory(String opt, Map<String,String> mandatory) {\n  return mandatory.keySet().stream().anyMatch(k -> opt.startsWith(k));\n}","typeGuard":null,"tryCatchPattern":"try {\n  launcher.start();\n} catch (MessageException e) {\n  if (e.getMessage().contains(\"overwrites\")) {\n    log.error(\"User JVM option conflicts with a mandatory option\", e);\n  }\n}","preventionTips":["Consult the mandatory option list for each process type before customizing javaOpts","Keep user JVM options limited to non-reserved tuning flags","Test javaOpts changes on a staging node first"],"tags":["java","jvm","configuration-conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}