apache/hadoop · error · RuntimeException

Error parsing recovery options: can't understand option "{ar

Error message

Error parsing recovery options: can't understand option "{args[i]}"

What it means

In the '-recover' argument-parsing loop, the only accepted token is '-force' (mapped to MetaRecoveryContext.FORCE_FIRST_CHOICE). Any following token the parser does not recognize raises RuntimeException 'Error parsing recovery options' naming the offending option, so the NameNode refuses to start with a malformed recovery command line.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java:1774

            startOpt.setForceFormat(true);
          } else {
            LOG.error("Invalid argument: " + args[i]);
            return null;
          }
        }
        return startOpt;
      } else if (StartupOption.RECOVER.getName().equalsIgnoreCase(cmd)) {
        if (startOpt != StartupOption.REGULAR) {
          throw new RuntimeException("Can't combine -recover with " +
              "other startup options.");
        }
        startOpt = StartupOption.RECOVER;
        while (++i < argsLen) {
          if (args[i].equalsIgnoreCase(
                StartupOption.FORCE.getName())) {
            startOpt.setForce(MetaRecoveryContext.FORCE_FIRST_CHOICE);
          } else {
            throw new RuntimeException("Error parsing recovery options: " + 
              "can't understand option \"" + args[i] + "\"");
          }
        }
      } else if (StartupOption.METADATAVERSION.getName().equalsIgnoreCase(cmd)) {
        startOpt = StartupOption.METADATAVERSION;
      } else {
        return null;
      }
    }
    return startOpt;
  }

  private static void setStartupOption(Configuration conf, StartupOption opt) {
    conf.set(DFS_NAMENODE_STARTUP_KEY, opt.name());
  }

  public static StartupOption getStartupOption(Configuration conf) {
    return StartupOption.valueOf(conf.get(DFS_NAMENODE_STARTUP_KEY,

View on GitHub (pinned to 2add963021)

Solutions

1. Use the exact supported form: 'hdfs namenode -recover -force' (force picks the first choice for every edit-log decision instead of prompting).
2. Remove every other token after '-recover'; if you needed another option, it belongs in a separate command.
3. Re-check the spelling of '-force' (case-insensitive per equalsIgnoreCase, but the dash is required).

Example fix

# before
hdfs namenode -recover -interactive

# after
hdfs namenode -recover -force   # '-force' is the only option '-recover' accepts

# accept only the documented form
if cmd == 'hdfs namenode -recover':
    tail = args[args.index('-recover')+1:]
    if any(a.lower() not in ('-force',) for a in tail):
        abort("-recover accepts only -force")

When it happens

Trigger: 'hdfs namenode -recover <token>' where <token> is anything but '-force' - e.g., '-recover -interactive', '-recover force' (missing dash), or a flag meant for another mode like '-recover -bootstrapStandby'.

Common situations: Typos or missing dashes in recovery flags; operators guessing at non-existent recovery options during an incident; scripts passing extra flags into the recover invocation.

Related errors

• Can't combine -recover with other startup options.
• The \"downgrade\" option is no longer supported since it may
• Failed to convert \"{s}\" to RollingUpgradeStartupOption
• user requested stop
• Illegal argument: ${arg}

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