apache/hadoop · error · IllegalArgumentException

Number of liststatus threads is invalid: {value}

Error message

Number of liststatus threads is invalid: {value}

What it means

The -numListstatusThreads option value must parse as a Java int (thread pool size for the listing phase's listStatus calls). Integer.parseInt failed and OptionsParser rethrows IllegalArgumentException with the offending value. Floats, words, and locale-formatted numbers are rejected.

Source

Thrown at hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/OptionsParser.java:179

    if (command.hasOption(DistCpOptionSwitch.BANDWIDTH.getSwitch())) {
      try {
        final Float mapBandwidth = Float.parseFloat(
            getVal(command, DistCpOptionSwitch.BANDWIDTH.getSwitch()));
        builder.withMapBandwidth(mapBandwidth);
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Bandwidth specified is invalid: " +
            getVal(command, DistCpOptionSwitch.BANDWIDTH.getSwitch()), e);
      }
    }

    if (command.hasOption(
        DistCpOptionSwitch.NUM_LISTSTATUS_THREADS.getSwitch())) {
      try {
        final Integer numThreads = Integer.parseInt(getVal(command,
            DistCpOptionSwitch.NUM_LISTSTATUS_THREADS.getSwitch()));
        builder.withNumListstatusThreads(numThreads);
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException(
            "Number of liststatus threads is invalid: " + getVal(command,
                DistCpOptionSwitch.NUM_LISTSTATUS_THREADS.getSwitch()), e);
      }
    }

    if (command.hasOption(DistCpOptionSwitch.MAX_MAPS.getSwitch())) {
      try {
        final Integer maps = Integer.parseInt(
            getVal(command, DistCpOptionSwitch.MAX_MAPS.getSwitch()));
        builder.maxMaps(maps);
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Number of maps is invalid: " +
            getVal(command, DistCpOptionSwitch.MAX_MAPS.getSwitch()), e);
      }
    }

    if (command.hasOption(DistCpOptionSwitch.COPY_STRATEGY.getSwitch())) {
      builder.withCopyStrategy(

View on GitHub (pinned to 2add963021)

Solutions

1. Pass a plain integer, e.g. -numListstatusThreads 10.
2. Remove decimal points and separators from the value.
3. Validate numeric options in the launching script before invoking distcp.

Example fix

# before
hadoop distcp -numListstatusThreads 8.0 hdfs://nn/src hdfs://nn/tgt

# after
hadoop distcp -numListstatusThreads 8 hdfs://nn/src hdfs://nn/tgt

// Wrapper validation: -numListstatusThreads must be a plain integer
private static void checkInt(String flag, String v) {
  if (!v.matches("[0-9]+")) {
    throw new IllegalArgumentException(flag + " must be an integer, got: " + v);
  }
}
checkInt("-numListstatusThreads", args[i + 1]);

try {
  OptionsParser.parse(args);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Number of liststatus threads is invalid")) {
    throw new IllegalArgumentException("Fix -numListstatusThreads to a plain integer", e);
  }
  throw e;
}

When it happens

Trigger: -numListstatusThreads 8.0, -numListstatusThreads four, or a comma-grouped value like 1,0 from a template.

Common situations: copy-pasted values with decimal points; scripts templating numbers with separators; operators confusing this listing-phase option with map count (-m).

Related errors

• Bandwidth specified is invalid: {value}
• Number of maps is invalid: {value}
• blocksPerChunk is invalid: {chunkSizeStr}
• copyBufferSize is invalid: {copyBufferSizeStr}
• Unable to parse arguments. {args}

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