{"record":{"id":"2542d4666dd3d2fd","repo":"apache/hadoop","slug":"invalid-checksum-type-useropt-useropt-default","errorCode":null,"errorMessage":"Invalid checksum type: userOpt=${userOpt}, default=${defaultChecksumOpt}, effective=null","messagePattern":"Invalid checksum type: userOpt=(.+?), default=(.+?), effective=null","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/impl/DfsClientConf.java","lineNumber":417,"sourceCode":"\n  // Construct a checksum option from conf\n  public static ChecksumOpt getChecksumOptFromConf(Configuration conf) {\n    DataChecksum.Type type = getChecksumType(conf);\n    int bytesPerChecksum = conf.getInt(DFS_BYTES_PER_CHECKSUM_KEY,\n        DFS_BYTES_PER_CHECKSUM_DEFAULT);\n    return new ChecksumOpt(type, bytesPerChecksum);\n  }\n\n  /** create a DataChecksum with the given option. */\n  public DataChecksum createChecksum(ChecksumOpt userOpt) {\n    // Fill in any missing field with the default.\n    ChecksumOpt opt = ChecksumOpt.processChecksumOpt(\n        defaultChecksumOpt, userOpt);\n    DataChecksum dataChecksum = DataChecksum.newDataChecksum(\n        opt.getChecksumType(),\n        opt.getBytesPerChecksum());\n    if (dataChecksum == null) {\n      throw new HadoopIllegalArgumentException(\"Invalid checksum type: userOpt=\"\n          + userOpt + \", default=\" + defaultChecksumOpt\n          + \", effective=null\");\n    }\n    return dataChecksum;\n  }\n\n  @VisibleForTesting\n  public int getBlockWriteLocateFollowingInitialDelayMs() {\n    return blockWriteLocateFollowingInitialDelayMs;\n  }\n\n  public int getBlockWriteLocateFollowingMaxDelayMs() {\n    return blockWriteLocateFollowingMaxDelayMs;\n  }\n\n  /**\n   * @return the hdfsTimeout\n   */","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/impl/DfsClientConf.java#L399-L435","documentation":"On the write path the client builds a DataChecksum from the effective checksum option: dfs.checksum.type / dfs.bytes-per-checksum defaults merged with any per-call ChecksumOpt. DataChecksum.newDataChecksum returns null for types that cannot back a writer (NULL, DEFAULT, MIXED, or an unrecognized value), and DfsClientConf.createChecksum converts that null into HadoopIllegalArgumentException.","triggerScenarios":"FileSystem.create/append with dfs.checksum.type set to an invalid string ('md5', 'none', a typo) or to null/default/mixed; or passing a ChecksumOpt whose type resolves to one of the non-creatable values.","commonSituations":"Copy-pasted configuration meant to 'disable checksums' — NULL cannot create a client-side checksummer, so checksum-free writes are not configured this way; typos in hdfs-site.xml; code building ChecksumOpt from unvalidated user input.","solutions":["Set dfs.checksum.type to crc32 or crc32c (case-insensitive).","Remove the key entirely to fall back to the built-in default.","Validate any ChecksumOpt passed to FileSystem.create() — only CRC32/CRC32C can create a client checksummer.","Do not set the client-side checksum type to null expecting checksum-free writes; that combination is rejected here by design."],"exampleFix":"# before (hdfs-site.xml)\n<property><name>dfs.checksum.type</name><value>md5</value></property>\n\n# after\n<property><name>dfs.checksum.type</name><value>crc32c</value></property>","handlingStrategy":"validation","validationCode":"String type = conf.get(\"dfs.checksum.type\", \"crc32\");\nSet<String> valid = Set.of(\"crc32\", \"crc32c\");\nif (!valid.contains(type.toLowerCase(Locale.ROOT))) {\n  throw new IllegalArgumentException(\n      \"dfs.checksum.type must be one of \" + valid + \", got: \" + type);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate dfs.checksum.type at job/client startup, before any create() call.","Do not set the checksum type to null/none to seek checksum-free writes — it is rejected here by design.","When building ChecksumOpt from user input, restrict it to CRC32/CRC32C."],"tags":["hdfs","checksum","configuration","write-path","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}