apache/hadoop · error · IllegalArgumentException

option {} requires 1 argument.

Error message

option {} requires 1 argument.

What it means

StringUtils.popOptionWithArgument iterates the argument list looking for an exact match of the option name (stopping early at a '--' separator). When it finds the name, it removes it and consumes the next token as the option's value; if the option was the last token in the list, there is nothing to consume and it throws this IllegalArgumentException. The parser scans the whole list, so the option being last anywhere-after-a-'--' just returns null instead.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/StringUtils.java:1185

   *
   * @param name  Name of the option to remove.  Example: -foo.
   * @param args  List of arguments.
   * @return      null if the option was not found; the value of the 
   *              option otherwise.
   * @throws IllegalArgumentException if the option's argument is not present
   */
  public static String popOptionWithArgument(String name, List<String> args)
      throws IllegalArgumentException {
    String val = null;
    for (Iterator<String> iter = args.iterator(); iter.hasNext(); ) {
      String cur = iter.next();
      if (cur.equals("--")) {
        // stop parsing arguments when you see --
        break;
      } else if (cur.equals(name)) {
        iter.remove();
        if (!iter.hasNext()) {
          throw new IllegalArgumentException("option " + name + " requires 1 " +
              "argument.");
        }
        val = iter.next();
        iter.remove();
        break;
      }
    }
    return val;
  }
  
  /**
   * From a list of command-line arguments, remove an option.
   *
   * @param name  Name of the option to remove.  Example: -foo.
   * @param args  List of arguments.
   * @return      true if the option was found and removed; false otherwise.
   */
  public static boolean popOption(String name, List<String> args) {

View on GitHub (pinned to 2add963021)

Solutions

  1. Supply the missing value token: '--conf core-site.xml'.
  2. Pre-scan the args list: if the option name is present at the last index (and not preceded by '--'), fail with a usage message before calling popOptionWithArgument.
  3. Catch IllegalArgumentException and print the tool's usage text naming the option.
  4. In scripts, guard with a variable check (e.g. [ -n "$CONF" ] && set -- --conf "$CONF" "$@") so the option is only appended together with its value.

Example fix

// before
List<String> args = new ArrayList<>(Arrays.asList("--conf"));
String conf = StringUtils.popOptionWithArgument("--conf", args);
// throws: option --conf requires 1 argument.

// after
List<String> args = new ArrayList<>(Arrays.asList("--conf", "core-site.xml"));
String conf = StringUtils.popOptionWithArgument("--conf", args);
Defensive patterns

Strategy: validation

Validate before calling

// fail with usage text before parsing if option lacks a value token
static boolean optionHasValue(List<String> args, String name) {
  for (int i = 0; i < args.size(); i++) {
    if (args.get(i).equals("--")) return true; // parsing stops; ok
    if (args.get(i).equals(name)) {
      return i + 1 < args.size();
    }
  }
  return true; // option absent
}

if (!optionHasValue(args, "--conf")) {
  System.err.println("Missing value for --conf");
  printUsage();
  System.exit(1);
}
String conf = StringUtils.popOptionWithArgument("--conf", args);

Try / catch

try {
  conf = StringUtils.popOptionWithArgument("--conf", args);
} catch (IllegalArgumentException e) {
  System.err.println("Error: " + e.getMessage());
  printUsage();
  System.exit(2);
}

Prevention

When it happens

Trigger: StringUtils.popOptionWithArgument("--conf", java.util.Arrays.asList("--conf")); a list like ["-v", "--conf"] where --conf is final; shell scripts or Java tool drivers where the user supplied the flag but its value was swallowed by quoting bugs or dropped entirely. Note the option value itself is taken verbatim: ["--conf", "--fs"] does NOT throw — '--fs' becomes the value.

Common situations: Command-line tools built on StringUtils.popOptionWithArgument where the user forgot the value ('hdfs --conf'); shell quoting that eats an empty argument; scripts conditionally appending an option without its argument when a variable is empty.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/e81a08750bab4269. Report an issue: GitHub.