apache/hadoop · error · HadoopIllegalArgumentException

usage: -confKey [key]

Error message

usage: -confKey [key]

What it means

The -confKey mode of 'hdfs getconf' is handled by PrintConfKeyCommandHandler, whose checkArgs demands exactly one positional argument: the configuration key to print. Zero arguments or more than one triggers this HadoopIllegalArgumentException whose text is the mode's usage line ('usage: -confKey [key]').

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/GetConf.java:261

      List<ConfiguredNNAddress> cnnlist = DFSUtil.flattenAddressMap(
          DFSUtil.getNNServiceRpcAddressesForCluster(config));
      if (!cnnlist.isEmpty()) {
        for (ConfiguredNNAddress cnn : cnnlist) {
          InetSocketAddress rpc = cnn.getAddress();
          tool.printOut(rpc.getHostName()+":"+rpc.getPort());
        }
        return 0;
      }
      tool.printError("Did not get namenode service rpc addresses.");
      return -1;
    }
  }
  
  static class PrintConfKeyCommandHandler extends CommandHandler {
    @Override
    protected void checkArgs(String[] args) {
      if (args.length != 1) {
        throw new HadoopIllegalArgumentException(
            "usage: " + Command.CONFKEY.getUsage());
      }
    }

    @Override
    int doWorkInternal(GetConf tool, String[] args) throws Exception {
      this.key = args[0];
      return super.doWorkInternal(tool, args);
    }
  }
  
  private final PrintStream out; // Stream for printing command output
  private final PrintStream err; // Stream for printing error

  GetConf(Configuration conf) {
    this(conf, System.out, System.err);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Pass exactly one key: 'hdfs getconf -confKey dfs.replication'.
2. For multiple keys, call getconf once per key in a loop.
3. Guard scripts: skip or fail early when the key variable is unbound instead of running the bare command.

Example fix

# before
hdfs getconf -confKey
# usage: -confKey [key]

# after
hdfs getconf -confKey dfs.replication

if (key == null || key.trim().isEmpty() || key.contains(" ")) {
  throw new IllegalArgumentException(
      "-confKey needs exactly one non-empty configuration key");
}
ToolRunner.run(new GetConf(), new String[]{"-confKey", key});

try {
  return ToolRunner.run(new GetConf(), argv);
} catch (Exception e) {
  if (e.getMessage() != null && e.getMessage().startsWith("usage: -confKey")) {
    return 2; // signal usage error distinctly in scripts
  }
  throw e;
}

When it happens

Trigger: Running 'hdfs getconf -confKey' with no key, or 'hdfs getconf -confKey key1 key2' expecting several values at once.

Common situations: Script loops building the command when the key variable is empty; users trying to pass a comma-separated key list; trailing whitespace tokens parsed as extra args.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Did not expect argument: {}
• Invalid or extra Arguments: {}
• 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/540fb7b93573ea2c. Report an issue: GitHub.