{"record":{"id":"eb1e6615ccc94daa","repo":"apache/hadoop","slug":"the-value-d-does-not-map-to-a-valid-checksum-type","errorCode":null,"errorMessage":"The value %d does not map to a valid checksum Type","messagePattern":"The value (.+?) does not map to a valid checksum Type","errorType":"exception","errorClass":"InvalidChecksumSizeException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/DataChecksum.java","lineNumber":185,"sourceCode":"   */\n  public static DataChecksum newDataChecksum( DataInputStream in )\n                                 throws IOException {\n    int type = in.readByte();\n    int bpc = in.readInt();\n    DataChecksum summer = newDataChecksum(mapByteToChecksumType(type), bpc);\n    if ( summer == null ) {\n      throw new InvalidChecksumSizeException(\"Could not create DataChecksum \"\n          + \"of type \" + type + \" with bytesPerChecksum \" + bpc);\n    }\n    return summer;\n  }\n\n  private static Type mapByteToChecksumType(int type)\n      throws InvalidChecksumSizeException{\n    try {\n      return Type.valueOf(type);\n    } catch (IllegalArgumentException e) {\n      throw new InvalidChecksumSizeException(\"The value \"+type+\" does not map\"+\n        \" to a valid checksum Type\");\n    }\n  }\n  \n  /**\n   * Writes the checksum header to the output stream <i>out</i>.\n   *\n   * @param out output stream.\n   * @throws IOException raised on errors performing I/O.\n   */\n  public void writeHeader( DataOutputStream out ) \n                           throws IOException { \n    out.writeByte( type.id );\n    out.writeInt( bytesPerChecksum );\n  }\n\n  public byte[] getHeader() {\n    byte[] header = new byte[getChecksumHeaderSize()];","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/DataChecksum.java#L167-L203","documentation":"The first checksum header byte is mapped through DataChecksum.Type.valueOf(int); only 0 (CHECKSUM_NULL), 1 (CHECKSUM_CRC32) and 2 (CHECKSUM_CRC32C) are legal ids. Any other value raises InvalidChecksumSizeException ('The value %d does not map to a valid checksum Type') — the type slot holds garbage, or a checksum type the running Hadoop version does not know.","triggerScenarios":"Reading arbitrary/non-checksum bytes as a header because the stream or buffer is misaligned; corrupted block metadata filling the type byte with noise; a newer Hadoop writing a checksum type id that an older reader does not support (version skew).","commonSituations":"Rolling upgrades where datanodes and clients differ in version; manual edits or copying of block meta files; stream-positioning bugs in custom readers.","solutions":["Confirm every reader/writer in the cluster understands the checksum type in use (ids 0, 1, 2 in this version)","Realign the stream: verify you are actually reading at a checksum header boundary","Run `hdfs fsck` and re-replicate corrupted blocks","Complete rolling upgrades before old components read data written with new checksum types"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"static boolean isValidChecksumTypeId(int id) {\n  return id == DataChecksum.CHECKSUM_NULL\n      || id == DataChecksum.CHECKSUM_CRC32\n      || id == DataChecksum.CHECKSUM_CRC32C;\n}\n// before interpreting a header byte:\nif (!isValidChecksumTypeId(typeByte & 0xff)) {\n  throw new IOException(\"not positioned at a checksum header (type=\" + (typeByte & 0xff) + \")\");\n}","typeGuard":"static boolean isKnownChecksumType(int id) {\n  try {\n    org.apache.hadoop.util.DataChecksum.Type.valueOf(id);\n    return true;\n  } catch (IllegalArgumentException e) {\n    return false;\n  }\n}","tryCatchPattern":"catch (InvalidChecksumSizeException e) {\n  // type byte is not 0/1/2: either corruption or a newer checksum type than this build knows\n  if (isVersionSkewSuspected()) logUpgradeAdvice();\n  failOverToHealthyReplica();\n}","preventionTips":["Verify checksum-type compatibility before rolling upgrades (client, DN, NN versions)","Validate the type byte before treating a buffer as a checksum header","Never hand-edit or partially copy block meta files"],"tags":["hdfs","checksum","type-mapping","version-skew","corruption"],"backgroundTag":"invalid-checksum-type","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}