{"record":{"id":"b32d7de7e6daff57","repo":"apache/hadoop","slug":"invalid-value-bytesperchecksum-0","errorCode":null,"errorMessage":"Invalid value: bytesPerChecksum = {} <= 0","messagePattern":"Invalid value: bytesPerChecksum = (.+?) <= 0","errorType":"validation","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSOutputStream.java","lineNumber":233,"sourceCode":"    if (flag.contains(CreateFlag.NO_LOCAL_WRITE)) {\n      this.addBlockFlags.add(AddBlockFlag.NO_LOCAL_WRITE);\n    }\n    if (flag.contains(CreateFlag.NO_LOCAL_RACK)) {\n      this.addBlockFlags.add(AddBlockFlag.NO_LOCAL_RACK);\n    }\n    if (flag.contains(CreateFlag.IGNORE_CLIENT_LOCALITY)) {\n      this.addBlockFlags.add(AddBlockFlag.IGNORE_CLIENT_LOCALITY);\n    }\n    if (progress != null) {\n      DFSClient.LOG.debug(\"Set non-null progress callback on DFSOutputStream \"\n          +\"{}\", src);\n    }\n\n    initWritePacketSize();\n\n    this.bytesPerChecksum = checksum.getBytesPerChecksum();\n    if (bytesPerChecksum <= 0) {\n      throw new HadoopIllegalArgumentException(\n          \"Invalid value: bytesPerChecksum = \" + bytesPerChecksum + \" <= 0\");\n    }\n    if (blockSize % bytesPerChecksum != 0) {\n      throw new HadoopIllegalArgumentException(\"Invalid values: \"\n          + HdfsClientConfigKeys.DFS_BYTES_PER_CHECKSUM_KEY\n          + \" (=\" + bytesPerChecksum + \") must divide block size (=\" +\n          blockSize + \").\");\n    }\n    this.byteArrayManager = dfsClient.getClientContext().getByteArrayManager();\n  }\n\n  /**\n   * Ensures the configured writePacketSize never exceeds\n   * PacketReceiver.MAX_PACKET_SIZE.\n   */\n  private void initWritePacketSize() {\n    writePacketSize = dfsClient.getConf().getWritePacketSize();\n    if (writePacketSize > PacketReceiver.MAX_PACKET_SIZE) {","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSOutputStream.java#L215-L251","documentation":"When a DFSOutputStream is constructed (create or append), it reads bytesPerChecksum from the DataChecksum in effect and rejects values <= 0 with HadoopIllegalArgumentException. The value comes from dfs.bytes-per-checksum (default 512) or from an explicit ChecksumOpt passed to the create/append call. HDFS has no 'checksums off via zero' mode, so 0 or negative is always invalid configuration.","triggerScenarios":"Setting dfs.bytes-per-checksum to 0 or negative in the client or server config; passing new ChecksumOpt(DataChecksum.Type.CRC32C, 0) (or a computed value that underflows) to DistributedFileSystem.create(..., checksumOpt, ...); append inheriting a server-side value that was misconfigured.","commonSituations":"Copied config templates with dfs.bytes-per-checksum=0 intended to 'disable' checksumming (not supported - per-file NULL checksum must be requested via API, not by zeroing this key); property typos like 512 accidentally edited to 51 or -512; code computing bytesPerChecksum from user input without validation.","solutions":["Set dfs.bytes-per-checksum back to a sane positive value (512 is the default and standard).","If checksums genuinely must be disabled for a file, request the NULL checksum through the API (ChecksumOpt with DataChecksum.Type.NULL) rather than zeroing the size property - the size must still be > 0.","Validate any programmatically-built ChecksumOpt before calling create: assert opt.getBytesPerChecksum() > 0.","Check both client-side and server-side configs - append picks up the server's value, so a bad NN config hits even clean clients."],"exampleFix":"// before\nconf.setInt(\"dfs.bytes-per-checksum\", 0); // hoping to disable checksums\nFileSystem fs = FileSystem.get(conf);\n\n// after\nconf.unset(\"dfs.bytes-per-checksum\"); // fall back to default 512\n// to disable checksums per file, use the API instead:\n// ((DistributedFileSystem) fs).create(path, ..., new ChecksumOpt(DataChecksum.Type.NULL, 512), ...);","handlingStrategy":"validation","validationCode":"int bpc = checksumOpt != null ? checksumOpt.getBytesPerChecksum() : 512;\nif (bpc <= 0) throw new IllegalArgumentException(\"bytesPerChecksum must be > 0, got \" + bpc);\nFSDataOutputStream out = fs.create(path, true, 4096, (short) 3, 128L * 1024 * 1024, checksumOpt);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never set dfs.bytes-per-checksum to 0 to disable checksums - use the per-file NULL checksum API.","Validate programmatically built ChecksumOpt values at config-load time.","Assert the property at startup: Preconditions.checkArgument(conf.getInt(\"dfs.bytes-per-checksum\", 512) > 0).","Check server-side config too - append inherits the NameNode's value."],"tags":["hdfs","hdfs-client","config","checksum","validation"],"backgroundTag":"invalid-checksum-config","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}