SonarSource/sonarqube · error · IllegalArgumentException

Only a single command-line argument is accepted (absolute pa

Error message

Only a single command-line argument is accepted (absolute path to configuration file)

What it means

ConfigurationUtils.loadPropsFromCommandLineArgs is used by process launchers (search server, web server) that must receive exactly one argument: the absolute path to a generated configuration file. Any other argument count throws this IllegalArgumentException before any file is read.

Source

Thrown at server/sonar-process/src/main/java/org/sonar/process/ConfigurationUtils.java:40

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.util.Properties;
import org.apache.commons.io.IOUtils;

import static org.sonar.process.FileUtils2.deleteQuietly;

public final class ConfigurationUtils {

  private ConfigurationUtils() {
    // Utility class
  }

  static Props loadPropsFromCommandLineArgs(String[] args) {
    if (args.length != 1) {
      throw new IllegalArgumentException("Only a single command-line argument is accepted " +
        "(absolute path to configuration file)");
    }

    File propertyFile = new File(args[0]);
    Properties properties = new Properties();
    Reader reader = null;
    try {
      reader = new InputStreamReader(new FileInputStream(propertyFile), StandardCharsets.UTF_8);
      properties.load(reader);
    } catch (Exception e) {
      throw new IllegalStateException("Could not read properties from file: " + args[0], e);
    } finally {
      IOUtils.closeQuietly(reader);
      deleteQuietly(propertyFile);
    }
    return new Props(properties);
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Pass exactly one argument: the absolute path to the generated conf file (e.g. /opt/sonarqube/temp/conf/es.properties)
2. Quote paths containing spaces: java ... "$CONFIG_FILE"
3. Do not launch these main classes manually; start SonarQube via its standard StartSonar/linux scripts which build the argument
4. Inspect the launcher script and ensure it expands a single variable, not a list

Example fix

// before
java org.sonar.process.Search conf1.properties extra.flag
// after
java org.sonar.process.Search /opt/sonarqube/temp/conf/search.properties

if (args.length != 1 || !new File(args[0]).isAbsolute())
  throw new IllegalArgumentException("Expected exactly one arg: absolute path to conf file");

try { Props p = ConfigurationUtils.loadPropsFromCommandLineArgs(args); } catch (IllegalArgumentException e) { System.err.println(e.getMessage()); System.exit(64); }

When it happens

Trigger: Launching the process with zero arguments, or with more than one argument (extra flags, quoted paths splitting into two args, manually invoking the main class).

Common situations: Hand-crafting java -cp ... org.sonar.process.XxxServer commands; shell quoting causing a path with spaces to become multiple arguments; broken custom launcher scripts.

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

• Command-line argument must start with -D, for example -Dsona
• Could not read properties from file:
• %s is not a valid url
• Invalid Azure URL
• Invalid Azure URL or Personal Access Token

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