SonarSource/sonarqube · error · IllegalArgumentException

Command-line argument must start with -D, for example -Dsona

Error message

Command-line argument must start with -D, for example -Dsonar.jdbc.username=sonar. Got: %s

What it means

SonarQube server's command-line argument parser converts JVM args of the form -Dkey=value into Java system properties. Any argument that does not start with '-D' or lacks an '=' separator is rejected with this IllegalArgumentException. It is a strict startup-time validation of CLI syntax.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/config/CommandLineParser.java:55

    // complete with only the system properties that start with "sonar."
    for (Map.Entry<Object, Object> entry : System.getProperties().entrySet()) {
      String key = entry.getKey().toString();
      if (key.startsWith("sonar.")) {
        props.setProperty(key, entry.getValue().toString());
      }
    }
    return props;
  }

  /**
   * Convert strings "-Dkey=value" to properties
   */
  static Properties argumentsToProperties(String[] args) {
    Properties props = new Properties();
    for (String arg : args) {
      if (!arg.startsWith("-D") || !arg.contains("=")) {
        throw new IllegalArgumentException(String.format(
          "Command-line argument must start with -D, for example -Dsonar.jdbc.username=sonar. Got: %s", arg));
      }
      String key = StringUtils.substringBefore(arg, "=").substring(2);
      String value = StringUtils.substringAfter(arg, "=");
      props.setProperty(key, value);
    }
    return props;
  }
}

View on GitHub (pinned to 184c821202)

Solutions

Prefix the argument with -D, e.g. -Dsonar.jdbc.username=sonar
Ensure the argument contains an '=' separating key and value
Check shell quoting so '-Dkey=value' stays a single argument
Fix the calling script/wrapper that builds the argument array

Example fix

// before
String[] args = {"sonar.jdbc.username=sonar"};
// after
String[] args = {"-Dsonar.jdbc.username=sonar"};

Defensive patterns

Strategy: validation

Validate before calling

boolean isPropertyArg(String arg) { return arg != null && arg.startsWith("-D") && arg.contains("="); }
// filter before calling: Arrays.stream(args).filter(a -> { if (!isPropertyArg(a)) throw new IllegalArgumentException(a); return true; });

Type guard

static boolean isPropertyArg(String arg) { return arg != null && arg.startsWith("-D") && arg.contains("="); }

Try / catch

try { Properties p = CommandLine.argumentsToProperties(args); } catch (IllegalArgumentException e) { log.error("Bad CLI arg: {}", e.getMessage()); }

Prevention

Always prefix system properties with -D
Always include an = (empty value allowed as -Dkey=)
Quote arguments in shell scripts so they stay single tokens
Add a pre-start validation step for generated argument arrays

When it happens

Trigger: Calling CommandLine.argumentsToProperties (via props()) with an argument like 'sonar.jdbc.username=sonar' (missing -D prefix) or '-Dsonar.web.port' (missing =value).

Common situations: Hand-written start scripts passing flags without the -D prefix; quoting mistakes in shell scripts that split -D from the key; copy-pasting JVM flags like -Xmx or --foo into a properties-args list.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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