{"record":{"id":"17a3b136b6dd52a5","repo":"apache/hadoop","slug":"found-feature-flags-which-we-can-t-handle-please","errorCode":null,"errorMessage":"Found feature flags which we can't handle. Please upgrade your software.","messagePattern":"Found feature flags which we can't handle\\. Please upgrade your software\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/LayoutFlags.java","lineNumber":48,"sourceCode":" * Note: all flags starting with 'test' are reserved for unit test purposes.\n */\n@InterfaceAudience.Private\npublic class LayoutFlags {\n\n  /**\n   * Read next int from given input stream. If the value is not 0 (unsupported\n   * feature flags), throw appropriate IOException.\n   *\n   * @param in            The stream to read from.\n   * @throws IOException  If next byte read from given stream is not 0.\n   */\n  public static void read(DataInputStream in) throws IOException {\n    int length = in.readInt();\n    if (length < 0) {\n      throw new IOException(\"The length of the feature flag section \" +\n          \"was negative at \" + length + \" bytes.\");\n    } else if (length > 0) {\n      throw new IOException(\"Found feature flags which we can't handle. \" +\n          \"Please upgrade your software.\");\n    }\n  }\n\n  private LayoutFlags() {\n  }\n\n  public static void write(DataOutputStream out) throws IOException {\n    out.writeInt(0);\n  }\n}\n","sourceCodeStart":30,"sourceCodeEnd":60,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/LayoutFlags.java#L30-L60","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: newer release wrote the storage, old release started anyway\nexport PATH=/opt/hadoop-old/bin:$PATH && hdfs namenode\n// after: roll back to the pre-upgrade layout instead of downgrading\nhdfs namenode -rollingupgrade rollback","handlingStrategy":"try-catch","validationCode":"// Before starting an older binary on existing storage, check compatibility:\n// read the VERSION file in dfs.namenode.name.dir/current and compare its\n// layoutVersion with the one baked into the binary you are about to run\n// (org.apache.hadoop.hdfs.server.namenode.FSImageFormat / HdfsConstants).\n// If the binary's supported layout is older than the stored one, roll back\n// instead of downgrading.","typeGuard":null,"tryCatchPattern":"try {\n  startNameNode(storageDirs);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Found feature flags\")) {\n    // storage written by a newer release: start the matching (or newer)\n    // version, or perform a proper rollback - never retry with this binary\n  } else {\n    throw e;\n  }\n}","preventionTips":["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"],"tags":["hdfs","namenode","fsimage","layout-version","downgrade","version-incompatibility"],"backgroundTag":"version-incompatibility","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}