apache/hadoop · error · IllegalArgumentException

dfs.namenode.lazypersist.file.scrub.interval.sec must be zer

Error message

dfs.namenode.lazypersist.file.scrub.interval.sec must be zero (for disable) or greater than zero.

What it means

The lazy-persist file scrubber interval (dfs.namenode.lazypersist.file.scrub.interval.sec) must be zero (disabled) or positive. FSNamesystem reads it with conf.getInt and throws IllegalArgumentException for any negative value during construction, so the NameNode refuses to start until the property is corrected.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java:1027

          (conf.getFloat(
              DFS_NAMENODE_EDIT_LOG_AUTOROLL_MULTIPLIER_THRESHOLD,
              DFS_NAMENODE_EDIT_LOG_AUTOROLL_MULTIPLIER_THRESHOLD_DEFAULT) *
          conf.getLong(
              DFS_NAMENODE_CHECKPOINT_TXNS_KEY,
              DFS_NAMENODE_CHECKPOINT_TXNS_DEFAULT));
      this.editLogRollerInterval = conf.getInt(
          DFS_NAMENODE_EDIT_LOG_AUTOROLL_CHECK_INTERVAL_MS,
          DFS_NAMENODE_EDIT_LOG_AUTOROLL_CHECK_INTERVAL_MS_DEFAULT);
      this.editLogRollerMaxIntervalMs = conf.getLong(
          DFS_NAMENODE_EDIT_LOG_AUTOROLL_MAX_INTERVAL_MS,
          DFS_NAMENODE_EDIT_LOG_AUTOROLL_MAX_INTERVAL_MS_DEFAULT);

      this.lazyPersistFileScrubIntervalSec = conf.getInt(
          DFS_NAMENODE_LAZY_PERSIST_FILE_SCRUB_INTERVAL_SEC,
          DFS_NAMENODE_LAZY_PERSIST_FILE_SCRUB_INTERVAL_SEC_DEFAULT);

      if (this.lazyPersistFileScrubIntervalSec < 0) {
        throw new IllegalArgumentException(
            DFS_NAMENODE_LAZY_PERSIST_FILE_SCRUB_INTERVAL_SEC
                + " must be zero (for disable) or greater than zero.");
      }

      this.edekCacheLoaderDelay = conf.getInt(
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_INITIAL_DELAY_MS_KEY,
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_INITIAL_DELAY_MS_DEFAULT);
      this.edekCacheLoaderInterval = conf.getInt(
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_INTERVAL_MS_KEY,
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_INTERVAL_MS_DEFAULT);
      this.edekCacheLoaderMaxRetries = conf.getInt(
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_MAX_RETRIES_KEY,
          DFSConfigKeys.DFS_NAMENODE_EDEKCACHELOADER_MAX_RETRIES_DEFAULT);

      this.leaseRecheckIntervalMs = conf.getLong(
          DFS_NAMENODE_LEASE_RECHECK_INTERVAL_MS_KEY,
          DFS_NAMENODE_LEASE_RECHECK_INTERVAL_MS_DEFAULT);
      Preconditions.checkArgument(

View on GitHub (pinned to 2add963021)

Solutions

Set the property to 0 to disable scrubbing
Or set a positive interval in seconds (e.g. 300)
Restart the NameNode and confirm startup completes

Example fix

<!-- before -->
<property><name>dfs.namenode.lazypersist.file.scrub.interval.sec</name><value>-1</value></property>
<!-- after: 0 disables the scrubber -->
<property><name>dfs.namenode.lazypersist.file.scrub.interval.sec</name><value>0</value></property>

Defensive patterns

Strategy: validation

Validate before calling

int v = conf.getInt(
    DFSConfigKeys.DFS_NAMENODE_LAZY_PERSIST_FILE_SCRUB_INTERVAL_SEC,
    DFSConfigKeys.DFS_NAMENODE_LAZY_PERSIST_FILE_SCRUB_INTERVAL_SEC_DEFAULT);
if (v < 0) {
  throw new IllegalArgumentException(
      "scrub interval must be 0 (disabled) or positive, got " + v);
}

Prevention

Range-check numeric Hadoop config keys in your config management before deploy
Remember this property uses 0 for disabled, not -1
Document the accepted range next to the property in your site templates

When it happens

Trigger: Setting dfs.namenode.lazypersist.file.scrub.interval.sec to a negative number in hdfs-site.xml (commonly -1 chosen as an 'off' convention, which this property does not accept — it wants 0).

Common situations: Operators using -1-as-disabled habits from other Hadoop properties; templated configs with a sign typo; values pasted with a stray dash.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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