apache/hadoop · critical · IOException

The length of the feature flag section was negative at {} by

Error message

The length of the feature flag section was negative at {} bytes.

What it means

LayoutFlags.read consumes an int in the fsimage/segment header reserved for future on-disk feature flags; today only 0 is valid. A negative value is meaningless as a length and signals that the stream is being read from the wrong position or the file is damaged - effectively an image-corruption detector.

Source

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

 * LayoutFlags represent features which the FSImage and edit logs can either
 * support or not, independently of layout version.
 * 
 * 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

1. Treat it as corruption: restore the previous good fsimage from the checkpoint/backup directories (image + matching .md5)
2. Verify integrity: compare fsimage_XXXX against its fsimage_XXXX.md5 companion before loading
3. If the file was copied, recopy in binary mode; check disk and filesystem health (dmesg, smartctl) on the NameNode

// Before loading, verify the image against its md5 sidecar
import org.apache.hadoop.hdfs.server.namenode.FSImageFormatProtobuf; // helper APIs vary
// simple shell-level guard:
//   cd $dfs.namenode.name.dir/current && md5sum -c <(sed 's/ /  /' fsimage_000*.md5)
// a failed checksum means the image is corrupt - restore a checkpoint instead of loading

try {
  namenode.loadFsImage(); // or BackupNode/secondary ingestion
} catch (IOException e) {
  if (e.getMessage().contains("feature flag section")) {
    // corruption / wrong file: restore previous fsimage from backup dirs; do NOT retry the same file
  } else {
    throw e;
  }
}

When it happens

Trigger: A NameNode/BackupNode reading a truncated or byte-corrupted fsimage; feeding a non-image file (edit segment, .md5 sidecar, empty file) into an image loader; reading a header at the wrong offset after prior corruption.

Common situations: Checkpoint interrupted by crash/power loss leaving a partial fsimage; failing disks flipping bytes; image files copied in text mode or truncated during transfer between nodes.

Related errors

• Content-Length header is not provided by the namenode when t
• Failed to load FSImage file, see error(s) above for more inf
• Safe mode should be turned ON in order to create namespace i
• Could not find image with txid " + txid
• GetImage failed. " + StringUtils.stringifyException(t)

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