apache/hadoop · error · HadoopIllegalArgumentException

Invalid value configured for dfs.datanode.disk.check.min.gap

Error message

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

What it means

DatasetVolumeChecker reads dfs.datanode.disk.check.min.gap (default 15 minutes) - the minimum interval between two successive health checks of the same volume, used by ThrottledAsyncChecker. Negative durations are rejected with HadoopIllegalArgumentException; zero is allowed and means no throttling gap.

Source

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

    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 + " - "
          + minDiskCheckGapMs + " (should be >= 0)");
    }

    diskCheckTimeout = conf.getTimeDuration(
        DFSConfigKeys.DFS_DATANODE_DISK_CHECK_TIMEOUT_KEY,
        DFSConfigKeys.DFS_DATANODE_DISK_CHECK_TIMEOUT_DEFAULT,
        TimeUnit.MILLISECONDS);

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

    lastAllVolumesCheck = timer.monotonicNow() - minDiskCheckGapMs;

    if (maxVolumeFailuresTolerated < DataNode.MAX_VOLUME_FAILURE_TOLERATED_LIMIT) {

View on GitHub (pinned to 2add963021)

Solutions

1. Use 0 or a positive duration: dfs.datanode.disk.check.min.gap=0 disables the gap, any positive value throttles
2. Keep the 15m default unless checks are impacting IO
3. Restart the DataNode after fixing hdfs-site.xml

Example fix

# before (hdfs-site.xml)
<property><name>dfs.datanode.disk.check.min.gap</name><value>-1s</value></property>

# after
<property><name>dfs.datanode.disk.check.min.gap</name><value>0</value></property>

long gap = conf.getTimeDuration(DFSConfigKeys.DFS_DATANODE_DISK_CHECK_MIN_GAP_KEY,
    DFSConfigKeys.DFS_DATANODE_DISK_CHECK_MIN_GAP_DEFAULT, TimeUnit.MILLISECONDS);
if (gap < 0) throw new IllegalStateException("dfs.datanode.disk.check.min.gap must be >= 0, got " + gap);

When it happens

Trigger: Setting dfs.datanode.disk.check.min.gap to a negative duration such as -1ms or '-1s' in hdfs-site.xml; the constructor check minDiskCheckGapMs < 0 fires during DataNode startup.

Common situations: Sign typos from copy-paste; attempt to express 'check as often as possible' as a negative 'lookbehind' style value; config templating or unit mistakes (e.g. '-1m' intended as 'default').

Related errors

• Invalid value configured for dfs.datanode.disk.check.timeout
• 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/73d6b3b22c86b34e. Report an issue: GitHub.