apache/hadoop · error · IllegalArgumentException

Failed to convert "{}" to RollingUpgradeAction

Error message

Failed to convert "{}" to RollingUpgradeAction

What it means

Argument parser for `hdfs dfsadmin -rollingUpgrade <action>`. RollingUpgradeAction.fromString uppercases the input and looks it up in a map that contains only QUERY, PREPARE, FINALIZE — plus the empty string, which maps to QUERY. An unrecognized action returns null and DFSAdmin throws IllegalArgumentException('Failed to convert "<action>" to RollingUpgradeAction'). Omitting the action entirely defaults to query and does NOT hit this error; only genuinely invalid strings do.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/DFSAdmin.java:411

            out.println(info);
        } else if (!info.isFinalized()) {
          out.println("Proceed with rolling upgrade:");
          out.println(info);
        } else {
          out.println("Rolling upgrade is finalized.");
          out.println(info);
        }
      } else {
        out.println("There is no rolling upgrade in progress or rolling " +
            "upgrade has already been finalized.");
      }
    }

    static int run(DistributedFileSystem dfs, String[] argv, int idx) throws IOException {
      final RollingUpgradeAction action = RollingUpgradeAction.fromString(
          argv.length >= 2? argv[1]: "");
      if (action == null) {
        throw new IllegalArgumentException("Failed to convert \"" + argv[1]
            +"\" to " + RollingUpgradeAction.class.getSimpleName());
      }

      System.out.println(action + " rolling upgrade ...");

      final RollingUpgradeInfo info = dfs.rollingUpgrade(action);
      switch(action){
      case QUERY:
        break;
      case PREPARE:
        Preconditions.checkState(info.isStarted());
        break;
      case FINALIZE:
        Preconditions.checkState(info == null || info.isFinalized());
        break;
      }
      printMessage(info, System.out);
      return 0;

View on GitHub (pinned to 2add963021)

Solutions

1. Use one of: hdfs dfsadmin -rollingUpgrade query | prepare | finalize (case-insensitive; empty means query)
2. Check the exact vocabulary: hdfs dfsadmin -help rollingUpgrade
3. Whitelist-validate the action in wrapper scripts before invoking dfsadmin
4. Map wrapper synonyms explicitly: start->prepare, status->query, done->finalize

Example fix

# before
$ hdfs dfsadmin -rollingUpgrade status
# IllegalArgumentException: Failed to convert "status" to RollingUpgradeAction

# after
$ hdfs dfsadmin -rollingUpgrade query

static final Set<String> ROLLING_UPGRADE_ACTIONS = Set.of("QUERY", "PREPARE", "FINALIZE");

static void validateAction(String a) {
  if (!ROLLING_UPGRADE_ACTIONS.contains(a.toUpperCase(Locale.ROOT)))
    throw new IllegalArgumentException("rollingUpgrade action must be query|prepare|finalize, got: " + a);
}

static boolean isRollingUpgradeAction(String s) {
  return s != null && ROLLING_UPGRADE_ACTIONS.contains(s.toUpperCase(Locale.ROOT));
}

When it happens

Trigger: hdfs dfsadmin -rollingUpgrade status ('status' is not an action); typos like prepair/finalise; scripts forwarding an arbitrary subcommand from a wrapper (e.g. a tool that accepts 'start' as a synonym).

Common situations: Operators expecting `-rollingUpgrade start`/`stop` semantics from other rolling-restart tools; help text written from memory instead of `hdfs dfsadmin -help rollingUpgrade`; wrapper scripts that pass through user input unvalidated.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• "{}" is not a valid value for a quota.
• Storage type {} is not available. Available storage types ar
• Cannot parse string "{s}"
• The \"downgrade\" option is no longer supported since it may
• Failed to convert \"{s}\" to RollingUpgradeStartupOption

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