apache/hadoop · critical · IOException

Found feature flags which we can't handle. Please upgrade yo

Error message

Found feature flags which we can't handle. Please upgrade your software.

What it means

The layout-flags int in the image/segment header is positive: the storage was written by a newer Hadoop that activated on-disk feature flags this binary does not implement. The reader deliberately refuses to interpret an unknown on-disk layout rather than risk misreading metadata (LayoutFlags.read only accepts 0).

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/LayoutFlags.java:48

 * Note: all flags starting with 'test' are reserved for unit test purposes.
 */
@InterfaceAudience.Private
public class LayoutFlags {

  /**
   * Read next int from given input stream. If the value is not 0 (unsupported
   * feature flags), throw appropriate IOException.
   *
   * @param in            The stream to read from.
   * @throws IOException  If next byte read from given stream is not 0.
   */
  public static void read(DataInputStream in) throws IOException {
    int length = in.readInt();
    if (length < 0) {
      throw new IOException("The length of the feature flag section " +
          "was negative at " + length + " bytes.");
    } else if (length > 0) {
      throw new IOException("Found feature flags which we can't handle. " +
          "Please upgrade your software.");
    }
  }

  private LayoutFlags() {
  }

  public static void write(DataOutputStream out) throws IOException {
    out.writeInt(0);
  }
}

View on GitHub (pinned to 2add963021)

Solutions

Run the Hadoop version that wrote the storage (or newer) against these directories
If the intent was to undo an upgrade, use the proper rollback path (e.g. hdfs namenode -rollingupgrade rollback) which restores the pre-upgrade image instead of downgrading binaries
Never let multiple version-skewed NameNodes share the same storage directories

Example fix

// before: newer release wrote the storage, old release started anyway
export PATH=/opt/hadoop-old/bin:$PATH && hdfs namenode
// after: roll back to the pre-upgrade layout instead of downgrading
hdfs namenode -rollingupgrade rollback

Defensive patterns

Strategy: try-catch

Validate before calling

// Before starting an older binary on existing storage, check compatibility:
// read the VERSION file in dfs.namenode.name.dir/current and compare its
// layoutVersion with the one baked into the binary you are about to run
// (org.apache.hadoop.hdfs.server.namenode.FSImageFormat / HdfsConstants).
// If the binary's supported layout is older than the stored one, roll back
// instead of downgrading.

Try / catch

try {
  startNameNode(storageDirs);
} catch (IOException e) {
  if (e.getMessage().contains("Found feature flags")) {
    // storage written by a newer release: start the matching (or newer)
    // version, or perform a proper rollback - never retry with this binary
  } else {
    throw e;
  }
}

Prevention

Use rolling-upgrade/rollback procedures instead of jar swaps across versions
Before any version change, record `hdfs namenode -version`-style info and the storage layoutVersion
Keep JournalNodes on a single version during rolling upgrades

When it happens

Trigger: Starting an older NameNode or JournalNode against storage directories (or journal segments) written by a newer Hadoop release that enabled a new layout feature; e.g. downgrading binaries after an upgrade instead of performing a rollback.

Common situations: Aborted upgrades handled by swapping jars; mixed versions among JournalNodes during a botched rolling upgrade; an old NN pointed at fresh dfs.namenode.name.dir contents.

Related errors

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