apache/hadoop · error · IllegalArgumentException

Period millis must be >= 0

Error message

Period millis must be >= 0

What it means

parseDecayPeriodMillis reads <ns>.decay-scheduler.period-ms (deprecated fallback <ns>.faircallqueue.decay-scheduler.period-ms, default 5000ms). Despite the message text saying '>= 0', the code rejects period <= 0, so the value must be strictly positive — it is the interval between decay sweeps. A zero or negative period would spin the sweep timer continuously, hence the guard at scheduler construction.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/DecayRpcScheduler.java:373

    return factor;
  }

  private static long parseDecayPeriodMillis(String ns, Configuration conf) {
    long period = conf.getLong(ns + "." +
        IPC_FCQ_DECAYSCHEDULER_PERIOD_KEY,
        0);
    if (period == 0) {
      period = conf.getLong(ns + "." +
          IPC_SCHEDULER_DECAYSCHEDULER_PERIOD_KEY,
          IPC_SCHEDULER_DECAYSCHEDULER_PERIOD_DEFAULT);
    } else if (period > 0) {
      LOG.warn((IPC_FCQ_DECAYSCHEDULER_PERIOD_KEY +
          " is deprecated. Please use " +
          IPC_SCHEDULER_DECAYSCHEDULER_PERIOD_KEY));
    }
    if (period <= 0) {
      throw new IllegalArgumentException("Period millis must be >= 0");
    }

    return period;
  }

  private static double[] parseThresholds(String ns, Configuration conf,
      int numLevels) {
    int[] percentages = conf.getInts(ns + "." +
        IPC_FCQ_DECAYSCHEDULER_THRESHOLDS_KEY);

    if (percentages.length == 0) {
      percentages = conf.getInts(ns + "." + IPC_DECAYSCHEDULER_THRESHOLDS_KEY);
      if (percentages.length == 0) {
        return getDefaultThresholds(numLevels);
      }
    } else {
      LOG.warn(IPC_FCQ_DECAYSCHEDULER_THRESHOLDS_KEY +
          " is deprecated. Please use " +

View on GitHub (pinned to 2add963021)

Solutions

1. Set ipc.<port>.decay-scheduler.period-ms to a positive millisecond value (default 5000).
2. If you intended a very fast sweep, use a small positive value (e.g., 100) rather than 0.
3. Remove the property to accept the default.

Example fix

// before (core-site.xml)
<property><name>ipc.8020.decay-scheduler.period-ms</name><value>0</value></property>
<!-- IllegalArgumentException: Period millis must be >= 0 -->

// after
<property><name>ipc.8020.decay-scheduler.period-ms</name><value>5000</value></property>

long p = conf.getTimeDuration("ipc." + port + ".decay-scheduler.period-ms", 5000, TimeUnit.MILLISECONDS);
if (p <= 0) {
  throw new ConfigException("decay-scheduler.period-ms must be > 0, got " + p);
}

When it happens

Trigger: Setting decay-scheduler.period-ms to 0 (a common 'disable' attempt) or a negative number under ipc.<port>; setting the deprecated faircallqueue key to 0; specifying a unit the parser reads as 0 (e.g., bare '0ms').

Common situations: Operators trying to disable the decay sweep by zeroing the period; tuning aggressive decay with tiny periods and fat-fingering to 0; copied configs from older Hadoop 2.x docs using the deprecated key.

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

• Decay Factor must be between 0 and 1
• Number of Priority Levels must be at least 1
• Number of thresholds should be {}. Was: {}
• responseTimeThresholds must match with the number of priorit
• responseTimeThreshold millis must be >= 0

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