apache/hadoop · error · HadoopIllegalArgumentException

Invalid value configured for dfs.datanode.disk.check.timeout

Error message

Invalid value configured for dfs.datanode.disk.check.timeout - {} (should be > 0)

What it means

DatasetVolumeChecker's constructor reads dfs.datanode.disk.check.timeout (default 10 minutes) as the max wall time a volume health check may take before the volume is declared dead. The first validation requires it to be strictly greater than 0; a zero or negative duration (e.g. '0s', '-1ms') aborts DataNode startup with HadoopIllegalArgumentException.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/checker/DatasetVolumeChecker.java:124

  private static final VolumeCheckContext IGNORED_CONTEXT =
      new VolumeCheckContext();

  private final ExecutorService checkVolumeResultHandlerExecutorService;

  /**
   * @param conf Configuration object.
   * @param timer {@link Timer} object used for throttling checks.
   */
  public DatasetVolumeChecker(Configuration conf, Timer timer)
      throws DiskErrorException {
    maxAllowedTimeForCheckMs = conf.getTimeDuration(
        DFS_DATANODE_DISK_CHECK_TIMEOUT_KEY,
        DFS_DATANODE_DISK_CHECK_TIMEOUT_DEFAULT,
        TimeUnit.MILLISECONDS);

    if (maxAllowedTimeForCheckMs <= 0) {
      throw new HadoopIllegalArgumentException("Invalid value configured for "
          + DFS_DATANODE_DISK_CHECK_TIMEOUT_KEY + " - "
          + maxAllowedTimeForCheckMs + " (should be > 0)");
    }

    this.timer = timer;

    maxVolumeFailuresTolerated = conf.getInt(
        DFS_DATANODE_FAILED_VOLUMES_TOLERATED_KEY,
        DFS_DATANODE_FAILED_VOLUMES_TOLERATED_DEFAULT);

    minDiskCheckGapMs = conf.getTimeDuration(
        DFSConfigKeys.DFS_DATANODE_DISK_CHECK_MIN_GAP_KEY,
        DFSConfigKeys.DFS_DATANODE_DISK_CHECK_MIN_GAP_DEFAULT,
        TimeUnit.MILLISECONDS);

    if (minDiskCheckGapMs < 0) {
      throw new HadoopIllegalArgumentException("Invalid value configured for "
          + DFS_DATANODE_DISK_CHECK_MIN_GAP_KEY + " - "

View on GitHub (pinned to 2add963021)

Solutions

1. Set a positive duration, e.g. dfs.datanode.disk.check.timeout=10m (the default)
2. To make checks fast rather than disabled, use a small positive value plus dfs.datanode.disk.check.min.gap to throttle
3. Restart the DataNode; the fail-fast check runs at construction, before any volume is touched

Example fix

# before (hdfs-site.xml)
<property><name>dfs.datanode.disk.check.timeout</name><value>0</value></property>

# after
<property><name>dfs.datanode.disk.check.timeout</name><value>10m</value></property>

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.hdfs.DFSConfigKeys;
import java.util.concurrent.TimeUnit;
long t = conf.getTimeDuration(DFSConfigKeys.DFS_DATANODE_DISK_CHECK_TIMEOUT_KEY,
    DFSConfigKeys.DFS_DATANODE_DISK_CHECK_TIMEOUT_DEFAULT, TimeUnit.MILLISECONDS);
if (t <= 0) throw new IllegalStateException("dfs.datanode.disk.check.timeout must be > 0, got " + t);

When it happens

Trigger: Setting dfs.datanode.disk.check.timeout=0 (or negative) in hdfs-site.xml - often done intending to 'disable' the timeout, which is not allowed; also bad duration syntax resolving to 0, or a units mistake like '0ms' meaning 'no timeout' in another system's semantics.

Common situations: Admins porting '0 disables it' conventions from other timeouts (e.g., dfs.datanode.socket.write.timeout=0 means no timeout there) to this key; templated configs injecting 0; regression after upgrading to Hadoop 3.x where DatasetVolumeChecker validation was added.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Invalid value configured for dfs.datanode.disk.check.min.gap
• Invalid value configured for dfs.datanode.disk.check.timeout
• Decay Factor must be between 0 and 1
• Period millis must be >= 0
• Cannot lock storage {root}. The directory is already locked

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/daf4ffd4f91d0e6f. Report an issue: GitHub.