apache/hadoop · error · MetricsException

The ${key} property must be non-negative. Value was ${value}

Error message

The ${key} property must be non-negative. Value was ${value}

What it means

getNonNegative() reads an integer property (used for roll-offset-interval-millis, default 30000) from the sink's SubsetConfiguration and rejects negative values with 'The <key> property must be non-negative. Value was <n>'. The message names the exact property key, so it tells you directly which value is bad. Non-numeric values fail earlier in commons-configuration conversion, so this specifically means a well-formed negative integer.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java:412

      throw new MetricsException("The flush interval property must be "
          + "at least 1 minute. Value was " + rollInterval);
    }

    return millis;
  }

  /**
   * Return the property value if it's non-negative and throw an exception if
   * it's not.
   *
   * @param key the property key
   * @param defaultValue the default value
   */
  private long getNonNegative(String key, int defaultValue) {
    int flushOffsetIntervalMillis = properties.getInt(key, defaultValue);

    if (flushOffsetIntervalMillis < 0) {
      throw new MetricsException("The " + key + " property must be "
          + "non-negative. Value was " + flushOffsetIntervalMillis);
    }

    return flushOffsetIntervalMillis;
  }

  /**
   * Throw a {@link MetricsException} if the given property is not set.
   *
   * @param key the key to validate
   */
  private void checkIfPropertyExists(String key) {
    if (!properties.containsKey(key)) {
      throw new MetricsException("Metrics2 configuration is missing " + key
          + " property");
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

Remove the property to accept the default (30000 ms)
Set it to 0 or a positive millisecond value (cluster guidance: at least 5 ms times the number of sink instances)
Do not use -1-as-disabled conventions for metrics2 sink properties

Example fix

# before
*.sink.rolling.roll-offset-interval-millis=-1  # '-1 means default' convention not honored here

# after
*.sink.rolling.roll-offset-interval-millis=30000

Defensive patterns

Strategy: validation

Validate before calling

int v = Integer.parseInt(properties.getProperty("roll-offset-interval-millis", "30000"));
if (v < 0) {
  throw new IllegalArgumentException(
      "roll-offset-interval-millis must be non-negative (0 or absent for none), got " + v);
}

Try / catch

try {
  sink.init(subsetConf);
} catch (MetricsException e) {
  // message names the exact key and the offending negative value
  LOG.error("{}", e.getMessage());
}

Prevention

Do not carry the '-1 means disabled' convention from other Hadoop properties into metrics2 sink settings
Use 0 or omit roll-offset-interval-millis when no stagger is wanted
For large clusters keep it at ~5ms per sink instance to avoid synchronized HDFS rolls

When it happens

Trigger: roll-offset-interval-millis=-1 or any negative value under <prefix>.sink.<instance>.

Common situations: Applying the widespread Hadoop convention that -1 means 'disabled/default' (valid for many other Hadoop properties) to this sink property, where 0 or omission is the correct way to express no offset.

Related errors

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