{"record":{"id":"e5308457dd914499","repo":"apache/hadoop","slug":"the-downgrade-option-is-no-longer-supported-si","errorCode":null,"errorMessage":"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).","messagePattern":"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\\)\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/HdfsServerConstants.java","lineNumber":111,"sourceCode":"  /** Startup options for rolling upgrade. */\n  enum RollingUpgradeStartupOption{\n    ROLLBACK, STARTED;\n\n    public String getOptionString() {\n      return StartupOption.ROLLINGUPGRADE.getName() + \" \"\n          + StringUtils.toLowerCase(name());\n    }\n\n    public boolean matches(StartupOption option) {\n      return option == StartupOption.ROLLINGUPGRADE\n          && option.getRollingUpgradeStartupOption() == this;\n    }\n\n    private static final RollingUpgradeStartupOption[] VALUES = values();\n\n    static RollingUpgradeStartupOption fromString(String s) {\n      if (\"downgrade\".equalsIgnoreCase(s)) {\n        throw new IllegalArgumentException(\n            \"The \\\"downgrade\\\" option is no longer supported\"\n                + \" since it may incorrectly finalize an ongoing rolling upgrade.\"\n                + \" For downgrade instruction, please see the documentation\"\n                + \" (http://hadoop.apache.org/docs/current/hadoop-project-dist/\"\n                + \"hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade).\");\n      }\n      for(RollingUpgradeStartupOption opt : VALUES) {\n        if (opt.name().equalsIgnoreCase(s)) {\n          return opt;\n        }\n      }\n      throw new IllegalArgumentException(\"Failed to convert \\\"\" + s\n          + \"\\\" to \" + RollingUpgradeStartupOption.class.getSimpleName());\n    }\n\n    public static String getAllOptionString() {\n      final StringBuilder b = new StringBuilder(\"<\");\n      for(RollingUpgradeStartupOption opt : VALUES) {","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/HdfsServerConstants.java#L93-L129","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","If you are mid-rolling-upgrade, choose the supported path: '-rollingUpgrade rollback' or finalize, per the upgrade state","Update automation to the current option set (rollback | started) and validate scripts against the target Hadoop release before the upgrade window"],"exampleFix":"# before\nhdfs namenode -rollingUpgrade downgrade\n\n# after (choose one supported path)\nhdfs namenode -rollingUpgrade rollback\n# or follow the documented downgrade: stop the cluster and\n# restart with the old-version binaries","handlingStrategy":"validation","validationCode":"String opt = args[i + 1];\nif (\"downgrade\".equalsIgnoreCase(opt)) {\n  throw new IllegalArgumentException(\"downgrade is unsupported in this release; \"\n      + \"follow https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade\");\n}\nRollingUpgradeStartupOption rsuo = RollingUpgradeStartupOption.fromString(opt);","typeGuard":null,"tryCatchPattern":"try {\n  RollingUpgradeStartupOption.fromString(opt);\n} catch (IllegalArgumentException e) {\n  System.err.println(\"Unsupported -rollingUpgrade option: \" + opt + \". Valid: \"\n      + RollingUpgradeStartupOption.getAllOptionString());\n  System.exit(2);\n}","preventionTips":["Validate upgrade scripts against the target Hadoop release's option set before the maintenance window","Reject the literal 'downgrade' early in automation with a pointer to the documented procedure","Track option-surface changes in release notes when upgrading Hadoop"],"tags":["hdfs","rolling-upgrade","namenode","cli","startup-option","version-compat"],"backgroundTag":"removed-cli-option","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}