apache/hadoop · error · HadoopIllegalArgumentException

Invalid or extra Arguments: {}

Error message

Invalid or extra Arguments: {}

What it means

DiskBalancerCLI ('hdfs diskbalancer') parses options with commons-cli and then inspects the leftover positional arguments. Only two positional tokens are legal: the subcommand (plan/execute/query/cancel/report/help) plus at most one operand (e.g. the hostname for -plan or the plan file path for -execute). Anything beyond index 1 is rejected with this HadoopIllegalArgumentException listing the extra tokens.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/DiskBalancerCLI.java:197

      res = 1;
    }
    System.exit(res);
  }

  /**
   * Execute the command with the given arguments.
   *
   * @param args command specific arguments.
   * @return exit code.
   * @throws Exception
   */
  @Override
  public int run(String[] args) throws Exception {
    Options opts = getOpts();
    CommandLine cmd = parseArgs(args, opts);
    String[] cmdArgs = cmd.getArgs();
    if (cmdArgs.length > 2) {
      throw new HadoopIllegalArgumentException(
          "Invalid or extra Arguments: " + Arrays
              .toString(Arrays.copyOfRange(cmdArgs, 2, cmdArgs.length)));
    }
    return dispatch(cmd);
  }

  /**
   * returns the Command Line Options.
   *
   * @return Options
   */
  private Options getOpts() {
    Options opts = new Options();
    addPlanCommands(opts);
    addHelpCommands(opts);
    addExecuteCommands(opts);
    addQueryCommands(opts);
    addCancelCommands(opts);

View on GitHub (pinned to 2add963021)

Solutions

1. Run 'hdfs diskbalancer -help' and match the subcommand syntax exactly (plan takes one host, execute takes one plan file path).
2. Remove the extra positional tokens named in the error message.
3. Quote operand values containing spaces and double-check that option values use '-' prefixed flags (e.g. -bandwidth 10) so they are not treated as positionals.

Example fix

# before
hdfs diskbalancer -execute /system/diskbalancer/plan.json /system/diskbalancer/node.json
# Invalid or extra Arguments: [node.json]

# after
hdfs diskbalancer -execute /system/diskbalancer/plan.json

// commons-cli style pre-check before DiskBalancerCLI.run
CommandLine cmd = parser.parse(getOpts(), args);
String[] positional = cmd.getArgs();
if (positional.length > 2) {
  throw new IllegalArgumentException("diskbalancer accepts at most 2 positional "
      + "arguments (command, operand); got " + Arrays.toString(positional));
}
cli.run(args);

try {
  return diskBalancerCLI.run(args);
} catch (HadoopIllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid or extra Arguments")) {
    System.err.println("Usage error; see 'hdfs diskbalancer -help'. Extra args: "
        + e.getMessage());
    return 1; // usage failure, not a cluster failure
  }
  throw e;
}

When it happens

Trigger: Invoking e.g. 'hdfs diskbalancer -execute plan.json nodeplan.json extra' (three positionals), or passing a value that the parser does not recognize as an option so it lands in getArgs(), or quoting mistakes that split one operand into several tokens.

Common situations: Copy-pasted commands with a stale extra argument; users adding a node list where only one host is accepted; scripts appending unquoted paths containing spaces.

Related errors

• Did not expect argument: {}
• usage: -confKey [key]
• invalid args: {}
• Unknown processor {} (valid processors: xml, binary, stats)
• Illegal option {}

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