{"record":{"id":"08e581f0c26c741b","repo":"apache/hadoop","slug":"dfs-datanode-parallel-volumes-load-threads-num","errorCode":null,"errorMessage":"dfs.datanode.parallel.volumes.load.threads.num = {} < 1","messagePattern":"dfs\\.datanode\\.parallel\\.volumes\\.load\\.threads\\.num = (.+?) < 1","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataStorage.java","lineNumber":353,"sourceCode":"    VolumeBuilder builder =\n        new VolumeBuilder(this, sd);\n    for (NamespaceInfo nsInfo : nsInfos) {\n      location.makeBlockPoolDir(nsInfo.getBlockPoolID(), datanode.getConf());\n\n      final BlockPoolSliceStorage bpStorage = getBlockPoolSliceStorage(nsInfo);\n      final List<StorageDirectory> dirs = bpStorage.loadBpStorageDirectories(\n          nsInfo, location, StartupOption.HOTSWAP, null, datanode.getConf());\n      builder.addBpStorageDirectories(nsInfo.getBlockPoolID(), dirs);\n    }\n    return builder;\n  }\n\n  static int getParallelVolumeLoadThreadsNum(int dataDirs, Configuration conf) {\n    final String key\n        = DFSConfigKeys.DFS_DATANODE_PARALLEL_VOLUME_LOAD_THREADS_NUM_KEY;\n    final int n = conf.getInt(key, dataDirs);\n    if (n < 1) {\n      throw new HadoopIllegalArgumentException(key + \" = \" + n + \" < 1\");\n    }\n    final int min = Math.min(n, dataDirs);\n    LOG.info(\"Using {} threads to upgrade data directories ({}={}, \"\n        + \"dataDirs={})\", min, key, n, dataDirs);\n    return min;\n  }\n\n  static class UpgradeTask {\n    private final StorageLocation dataDir;\n    private final Future<StorageDirectory> future;\n\n    UpgradeTask(StorageLocation dataDir, Future<StorageDirectory> future) {\n      this.dataDir = dataDir;\n      this.future = future;\n    }\n  }\n\n  /**","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataStorage.java#L335-L371","documentation":"getParallelVolumeLoadThreadsNum validates dfs.datanode.parallel.volumes.load.threads.num, the thread count used when upgrading/loading data directories in parallel. Any value below 1 is rejected immediately with HadoopIllegalArgumentException naming the key and value; when unset it defaults to the number of data directories.","triggerScenarios":"Setting dfs.datanode.parallel.volumes.load.threads.num to 0 or a negative number in hdfs-site.xml, then starting the datanode or entering any code path that computes parallel volume-load threads (e.g. upgrade via recoverTransitionRead).","commonSituations":"Copy-paste config with a stray 0; trying to 'disable parallelism' by setting 0 (not supported - use 1); templated config where an empty variable parses as 0.","solutions":["Set the property to a positive integer (1 for serial loading, roughly the disk count for parallel)","Or remove the property entirely to get the default (number of data dirs)","Lint hdfs-site.xml in CI so numeric floors are checked before deploy"],"exampleFix":"<!-- before -->\n<property>\n  <name>dfs.datanode.parallel.volumes.load.threads.num</name>\n  <value>0</value>\n</property>\n<!-- after -->\n<property>\n  <name>dfs.datanode.parallel.volumes.load.threads.num</name>\n  <value>1</value>\n</property>","handlingStrategy":"validation","validationCode":"int n = conf.getInt(\n    DFSConfigKeys.DFS_DATANODE_PARALLEL_VOLUME_LOAD_THREADS_NUM_KEY, numDataDirs);\nif (n < 1) {\n  throw new IllegalArgumentException(\n      DFSConfigKeys.DFS_DATANODE_PARALLEL_VOLUME_LOAD_THREADS_NUM_KEY + \" must be >= 1, got \" + n);\n}","typeGuard":null,"tryCatchPattern":"catch (HadoopIllegalArgumentException e) {\n  // config error: fix hdfs-site.xml value, no retry will help\n  failStartupWithConfigGuidance(e);\n}","preventionTips":["Use 1 to serialize volume loading; use ~disk count for parallelism; never 0","Lint numeric config properties in CI before deployment","Omit the property to inherit the sane default (number of data dirs)"],"tags":["hadoop","hdfs","datanode","configuration","validation","upgrade"],"backgroundTag":"invalid-config-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}