apache/hadoop · error · HadoopIllegalArgumentException

Bad argument: {}

Error message

Bad argument: {}

What it means

ZKFailoverController.badArg(String) prints USAGE to stderr and throws HadoopIllegalArgumentException('Bad argument: <arg>') when the ZKFC process is started with an unrecognized command-line argument. Usage is: 'hdfs zkfc [ -formatZK [-force] [-nonInteractive] ]'.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ha/ZKFailoverController.java:277

    } catch (Exception e) {
      LOG.error("The failover controller encounters runtime error: ", e);
      throw e;
    } finally {
      rpcServer.stopAndJoin();
      
      elector.quitElection(true);

      if (healthMonitor != null) {
        healthMonitor.shutdown();
        healthMonitor.join();
      }
    }
    return 0;
  }

  private void badArg(String arg) {
    printUsage();
    throw new HadoopIllegalArgumentException(
        "Bad argument: " + arg);
  }

  private void printUsage() {
    System.err.println(USAGE + "\n");
  }

  private int formatZK(boolean force, boolean interactive)
      throws IOException, InterruptedException, KeeperException {
    if (elector.parentZNodeExists()) {
      if (!force && (!interactive || !confirmFormat())) {
        return ERR_CODE_FORMAT_DENIED;
      }
      
      try {
        elector.clearParentZNode();
      } catch (IOException e) {
        LOG.error("Unable to clear zk parent znode", e);

View on GitHub (pinned to 2add963021)

Solutions

1. Run with no arguments or '-h' to print USAGE; only -formatZK, -force, -nonInteractive (and -h) are accepted here.
2. Fix the typo in the start script or systemd/init definition.
3. For custom arguments, parse them in the subclass's parseArgs before delegating to super, instead of passing them through.

Example fix

# before
hdfs zkfc -formatZ --force

# after
hdfs zkfc -formatZK -force -nonInteractive

Set<String> allowed = Set.of("-h", "-formatZK", "-force", "-nonInteractive");
for (String a : args) {
  if (!allowed.contains(a)) {
    throw new IllegalArgumentException("Unknown ZKFC argument: " + a);
  }
}

try {
  System.exit(ToolRunner.run(conf, new DFZKFailoverController(), args));
} catch (HadoopIllegalArgumentException e) {
  // USAGE was already printed; fix the flags in the launcher script
}

When it happens

Trigger: Launching the ZKFailoverController (hdfs zkfc / DFZKFailoverController subclass) with an unknown or misspelled flag, e.g. '-formatZ' instead of '-formatZK', or passing extra positional args after valid ones.

Common situations: Typos in startup scripts; scripts written for a different tool passing NameNode-style flags; custom ZKFailoverController subclasses (e.g. HDFS-ized ones) that accept extra args but the base class rejects them.

Related errors

• hadoop.security.authorizationis configured to true but servi
• ZK Failover Controller failed: {}
• Couldn't transition to active
• Unable to fence {}
• Expect either -getlevel or -setlevel

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