apache/hadoop · error · RuntimeException

Can't combine -recover with other startup options.

Error message

Can't combine -recover with other startup options.

What it means

While parsing NameNode command-line arguments, the '-recover' branch (StartupOption.RECOVER) throws RuntimeException if any other startup option was parsed first (startOpt != REGULAR). Recovery mode - which interactively picks edit-log choices to recover corrupt metadata - is mutually exclusive with every other startup option.

Source

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

      } else if (StartupOption.BOOTSTRAPSTANDBY.getName().equalsIgnoreCase(cmd)) {
        startOpt = StartupOption.BOOTSTRAPSTANDBY;
        return startOpt;
      } else if (StartupOption.INITIALIZESHAREDEDITS.getName().equalsIgnoreCase(cmd)) {
        startOpt = StartupOption.INITIALIZESHAREDEDITS;
        for (i = i + 1 ; i < argsLen; i++) {
          if (StartupOption.NONINTERACTIVE.getName().equals(args[i])) {
            startOpt.setInteractiveFormat(false);
          } else if (StartupOption.FORCE.getName().equals(args[i])) {
            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;
      }
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Run '-recover' alone: 'hdfs namenode -recover' (optionally '-recover -force').
2. Perform the other operation (format/upgrade/rollback/bootstrapStandby) as a separate command invocation.
3. Check 'hdfs namenode -h' / the official docs for which options each mode accepts.

Example fix

# before
hdfs namenode -format -recover

# after
hdfs namenode -recover   # recovery mode accepts no other startup options; run other operations separately

# validate the command line before invoking the NN
if args contains '-recover' and (len(args) > 2 or any of
    ['-format','-upgrade','-rollback','-bootstrapStandby','-initializeSharedEdits'] in args):
    abort("-recover must be the only startup option")

When it happens

Trigger: Invoking the NameNode with '-recover' combined with another option, e.g. 'hdfs namenode -format -recover', 'hdfs namenode -upgrade -recover', '-rollback -recover'; the option parser rejects the combination before the NN starts.

Common situations: Operators chaining flags out of caution during incident recovery ('it just had an upgrade, so also recover'); copy-pasted command lines; scripts appending flags conditionally until one run includes both.

Related errors

• Error parsing recovery options: can't understand option "{ar
• 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/0c72028b5e58ee03. Report an issue: GitHub.