{"record":{"id":"0b765a6ca25543f5","repo":"apache/hadoop","slug":"the-block-meta-file-header-is-corrupt","errorCode":null,"errorMessage":"The block meta file header is corrupt","messagePattern":"The block meta file header is corrupt","errorType":"exception","errorClass":"CorruptMetaHeaderException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockMetadataHeader.java","lineNumber":133,"sourceCode":"   * @throws IOException on error.\n   */\n  public static BlockMetadataHeader preadHeader(FileChannel fc)\n      throws IOException {\n    final byte arr[] = new byte[getHeaderSize()];\n    ByteBuffer buf = ByteBuffer.wrap(arr);\n\n    while (buf.hasRemaining()) {\n      if (fc.read(buf, buf.position()) <= 0) {\n        throw new CorruptMetaHeaderException(\"EOF while reading header from \"+\n            \"the metadata file. The meta file may be truncated or corrupt\");\n      }\n    }\n    short version = (short)((arr[0] << 8) | (arr[1] & 0xff));\n    DataChecksum dataChecksum;\n    try {\n      dataChecksum = DataChecksum.newDataChecksum(arr, 2);\n    } catch (InvalidChecksumSizeException e) {\n      throw new CorruptMetaHeaderException(\"The block meta file header is \"+\n          \"corrupt\", e);\n    }\n    return new BlockMetadataHeader(version, dataChecksum);\n  }\n\n  /**\n   * This reads all the fields till the beginning of checksum.\n   * @return Metadata Header\n   * @throws IOException\n   */\n  public static BlockMetadataHeader readHeader(DataInputStream in)\n      throws IOException {\n    try {\n      return readHeader(in.readShort(), in);\n    } catch (EOFException eof) {\n      // The attempt to read the header threw EOF, indicating there are not\n      // enough bytes in the meta file for the header.\n      throw new CorruptMetaHeaderException(\"EOF while reading header from meta\"+","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockMetadataHeader.java#L115-L151","documentation":"preadHeader successfully read the raw header bytes from the FileChannel, but DataChecksum.newDataChecksum(arr, 2) threw InvalidChecksumSizeException: the checksum descriptor at offset 2 encodes an invalid checksum size. Unlike the EOF case this is corruption of the header bytes, not truncation; it is wrapped in CorruptMetaHeaderException.","triggerScenarios":"Same FileChannel read path, with a .meta file long enough but whose checksum type/length bytes are garbage: wrong checksum type byte, insane header length, or unrelated data overwriting the file.","commonSituations":"Disk corruption; a wrong file sitting at the meta path; partially overwritten .meta files after crashes or buggy tooling.","solutions":["Identify the affected blocks with 'hdfs fsck /'","Delete the corrupt block/meta pair so HDFS re-replicates from healthy replicas","Investigate hardware/filesystem errors on the volume that produced the corrupt header"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"static boolean isCorruptMetaHeader(Throwable t) {\n  return t instanceof CorruptMetaHeaderException;\n}","tryCatchPattern":"try {\n  BlockMetadataHeader header = BlockMetadataHeader.preadHeader(fc);\n} catch (CorruptMetaHeaderException e) {\n  // header bytes are garbage: drop the replica pair and let NN re-replicate\n  deleteBlockAndMeta(block);\n}","preventionTips":["Treat CorruptMetaHeaderException as a corrupt-replica signal, never as transient I/O","Verify volume health (smartctl/xfs checks) when several meta headers corrupt at once"],"tags":["hdfs","datanode","block-metadata","corruption","checksum"],"backgroundTag":"corrupt-block-metadata","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}