apache/hadoop · error · IllegalArgumentException

Failed to convert \"{s}\" to RollingUpgradeStartupOption

Error message

Failed to convert \"{s}\" to RollingUpgradeStartupOption

What it means

RollingUpgradeStartupOption.fromString throws IllegalArgumentException for any string that is not (case-insensitively) a name of the enum, whose only members are ROLLBACK and STARTED (HdfsServerConstants.java:94-95). getAllOptionString() renders the accepted set as <rollback|started>. This is the NameNode startup option surface, distinct from 'hdfs dfsadmin -rollingUpgrade' verbs (query/prepare/finalize).

Source

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

    }

    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) {
        b.append(StringUtils.toLowerCase(opt.name())).append("|");
      }
      b.setCharAt(b.length() - 1, '>');
      return b.toString();
    }
  }

  /** Startup options */
  enum StartupOption{
    FORMAT  ("-format"),
    CLUSTERID ("-clusterid"),
    GENCLUSTERID ("-genclusterid"),

View on GitHub (pinned to 2add963021)

Solutions

1. Use one of the valid NameNode startup options: 'hdfs namenode -rollingUpgrade rollback' or '-rollingUpgrade started'
2. If you meant query/prepare/finalize, run those via 'hdfs dfsadmin -rollingUpgrade <query|prepare|finalize>' instead
3. Validate the option string against RollingUpgradeStartupOption.getAllOptionString() output before starting the NameNode

Example fix

# before
hdfs namenode -rollingUpgrade prepare   # not a startup option

# after
hdfs dfsadmin -rollingUpgrade prepare    # dfsadmin verb
hdfs namenode -rollingUpgrade started    # valid startup option

private static final Set<String> VALID_RU_OPTIONS =
    Set.of("rollback", "started");

boolean ok = VALID_RU_OPTIONS.contains(opt.toLowerCase(Locale.ROOT));
if (!ok) throw new IllegalArgumentException(
    "Invalid -rollingUpgrade option: " + opt + "; expected <rollback|started>");

static boolean isSupportedRollingUpgradeOption(String s) {
  return s != null && Arrays.stream(RollingUpgradeStartupOption.values())
      .anyMatch(o -> o.name().equalsIgnoreCase(s));
}

try {
  return RollingUpgradeStartupOption.fromString(s);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Bad rollingUpgrade option '" + s + "'. Valid: "
      + RollingUpgradeStartupOption.getAllOptionString(), e);
}

When it happens

Trigger: Running 'hdfs namenode -rollingUpgrade <value>' where <value> is a typo or a dfsadmin verb such as 'query', 'prepare' or 'finalize', which do not exist in this enum; any programmatic call of fromString with an unvalidated string.

Common situations: Confusing the dfsadmin rollingUpgrade subcommands with the NameNode -rollingUpgrade startup options; typos in hand-written upgrade scripts; option drift across Hadoop versions.

Related errors

• The \"downgrade\" option is no longer supported since it may
• Illegal argument: ${arg}
• Can't combine -recover with other startup options.
• Error parsing recovery options: can't understand option "{ar
• Failed to convert "{}" to RollingUpgradeAction

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