apache/hadoop · error · IllegalArgumentException

The \"downgrade\" option is no longer supported since it may

Error message

The \"downgrade\" option is no longer supported since it may incorrectly finalize an ongoing rolling upgrade. For downgrade instruction, please see the documentation (http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade).

What it means

HdfsServerConstants.RollingUpgradeStartupOption.fromString special-cases the literal 'downgrade' (case-insensitive) and throws IllegalArgumentException. The option was removed from Hadoop because issuing it could incorrectly finalize an ongoing rolling upgrade; the message itself points at the official downgrade documentation. Valid options are only the enum members ROLLBACK and STARTED (HdfsServerConstants.java:95).

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/HdfsServerConstants.java:111

  /** Startup options for rolling upgrade. */
  enum RollingUpgradeStartupOption{
    ROLLBACK, STARTED;

    public String getOptionString() {
      return StartupOption.ROLLINGUPGRADE.getName() + " "
          + StringUtils.toLowerCase(name());
    }

    public boolean matches(StartupOption option) {
      return option == StartupOption.ROLLINGUPGRADE
          && option.getRollingUpgradeStartupOption() == this;
    }

    private static final RollingUpgradeStartupOption[] VALUES = values();

    static RollingUpgradeStartupOption fromString(String s) {
      if ("downgrade".equalsIgnoreCase(s)) {
        throw new IllegalArgumentException(
            "The \"downgrade\" option is no longer supported"
                + " since it may incorrectly finalize an ongoing rolling upgrade."
                + " For downgrade instruction, please see the documentation"
                + " (http://hadoop.apache.org/docs/current/hadoop-project-dist/"
                + "hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade).");
      }
      for(RollingUpgradeStartupOption opt : VALUES) {
        if (opt.name().equalsIgnoreCase(s)) {
          return opt;
        }
      }
      throw new IllegalArgumentException("Failed to convert \"" + s
          + "\" to " + RollingUpgradeStartupOption.class.getSimpleName());
    }

    public static String getAllOptionString() {
      final StringBuilder b = new StringBuilder("<");
      for(RollingUpgradeStartupOption opt : VALUES) {

View on GitHub (pinned to 2add963021)

Solutions

1. Remove the downgrade option from the command and follow the documented manual downgrade procedure (HdfsRollingUpgrade.html#Downgrade: stop services and restart on the old-version software)
2. If you are mid-rolling-upgrade, choose the supported path: '-rollingUpgrade rollback' or finalize, per the upgrade state
3. Update automation to the current option set (rollback | started) and validate scripts against the target Hadoop release before the upgrade window

Example fix

# before
hdfs namenode -rollingUpgrade downgrade

# after (choose one supported path)
hdfs namenode -rollingUpgrade rollback
# or follow the documented downgrade: stop the cluster and
# restart with the old-version binaries

String opt = args[i + 1];
if ("downgrade".equalsIgnoreCase(opt)) {
  throw new IllegalArgumentException("downgrade is unsupported in this release; "
      + "follow https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade");
}
RollingUpgradeStartupOption rsuo = RollingUpgradeStartupOption.fromString(opt);

try {
  RollingUpgradeStartupOption.fromString(opt);
} catch (IllegalArgumentException e) {
  System.err.println("Unsupported -rollingUpgrade option: " + opt + ". Valid: "
      + RollingUpgradeStartupOption.getAllOptionString());
  System.exit(2);
}

When it happens

Trigger: Starting the NameNode with 'hdfs namenode -rollingUpgrade downgrade' (or 'hdfs --daemon start namenode -rollingUpgrade downgrade'), or any tooling/script that feeds the string 'downgrade' into RollingUpgradeStartupOption.fromString.

Common situations: Upgrade/runbook scripts written for an older Hadoop release replayed on a newer build where the option was removed; operators following pre-removal documentation during a rolling upgrade.

Related errors

• Failed to convert \"{s}\" to RollingUpgradeStartupOption
• Can't combine -recover with other startup options.
• Error parsing recovery options: can't understand option "{ar
• Illegal argument: ${arg}
• Failed to convert "{}" to RollingUpgradeAction

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