apache/hadoop · error · HadoopIllegalArgumentException

Feature %s unsupported at NameNode layout version %d. If a

Error message

Feature %s unsupported at NameNode layout version %d.  If a rolling upgrade is in progress, then it must be finalized before using this feature.

What it means

Error "Feature %s unsupported at NameNode layout version %d. If a rolling upgrade is in progress, then it must be finalized before using this feature." thrown in apache/hadoop.

Source

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

  /**
   * Performs a pre-condition check that the layout version in effect is
   * sufficient to support the requested {@link Feature}.  If not, then the
   * method throws {@link HadoopIllegalArgumentException} to deny the operation.
   * This exception class is registered as a terse exception, so it prevents
   * verbose stack traces in the NameNode log.  During a rolling upgrade, this
   * method is used to restrict usage of new features.  This prevents writing
   * new edit log operations that would be unreadable by the old software
   * version if the admin chooses to downgrade.
   *
   * @param f feature to check
   * @throws HadoopIllegalArgumentException if the current layout version in
   *     effect is insufficient to support the feature
   */
  private void requireEffectiveLayoutVersionForFeature(Feature f)
      throws HadoopIllegalArgumentException {
    int lv = getEffectiveLayoutVersion();
    if (!NameNodeLayoutVersion.supports(f, lv)) {
      throw new HadoopIllegalArgumentException(String.format(
          "Feature %s unsupported at NameNode layout version %d.  If a " +
          "rolling upgrade is in progress, then it must be finalized before " +
          "using this feature.", f, lv));
    }
  }

  void checkRollingUpgrade(String action) throws RollingUpgradeException {
    if (isRollingUpgrade()) {
      throw new RollingUpgradeException("Failed to " + action
          + " since a rolling upgrade is already in progress."
          + " Existing rolling upgrade info:\n" + rollingUpgradeInfo);
    }
  }

  RollingUpgradeInfo finalizeRollingUpgrade() throws IOException {
    final String operationName = "finalizeRollingUpgrade";
    checkSuperuserPrivilege(operationName);
    checkOperation(OperationCategory.WRITE);

View on GitHub (pinned to 2add963021)

Solutions

1. Finalize the rolling upgrade with 'hdfs dfsadmin -rollingUpgrade finalize' before using the feature, or use a NameNode version whose layout supports it.

When it happens

Trigger: A feature requiring a newer layout version is invoked while the NameNode layout is older, typically during a rolling upgrade.

Common situations: Using a new HDFS feature (e.g., EC, new snapshot ops) before finalizing an in-progress rolling upgrade.

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