{"record":{"id":"1b193cd7167cc472","repo":"apache/hadoop","slug":"the-key-property-must-be-non-negative-value-wa","errorCode":null,"errorMessage":"The ${key} property must be non-negative. Value was ${value}","messagePattern":"The (.+?) property must be non-negative\\. Value was (.+?)","errorType":"exception","errorClass":"MetricsException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java","lineNumber":412,"sourceCode":"      throw new MetricsException(\"The flush interval property must be \"\n          + \"at least 1 minute. Value was \" + rollInterval);\n    }\n\n    return millis;\n  }\n\n  /**\n   * Return the property value if it's non-negative and throw an exception if\n   * it's not.\n   *\n   * @param key the property key\n   * @param defaultValue the default value\n   */\n  private long getNonNegative(String key, int defaultValue) {\n    int flushOffsetIntervalMillis = properties.getInt(key, defaultValue);\n\n    if (flushOffsetIntervalMillis < 0) {\n      throw new MetricsException(\"The \" + key + \" property must be \"\n          + \"non-negative. Value was \" + flushOffsetIntervalMillis);\n    }\n\n    return flushOffsetIntervalMillis;\n  }\n\n  /**\n   * Throw a {@link MetricsException} if the given property is not set.\n   *\n   * @param key the key to validate\n   */\n  private void checkIfPropertyExists(String key) {\n    if (!properties.containsKey(key)) {\n      throw new MetricsException(\"Metrics2 configuration is missing \" + key\n          + \" property\");\n    }\n  }\n","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java#L394-L430","documentation":"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.","triggerScenarios":"roll-offset-interval-millis=-1 or any negative value under <prefix>.sink.<instance>.","commonSituations":"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.","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"],"exampleFix":"# before\n*.sink.rolling.roll-offset-interval-millis=-1  # '-1 means default' convention not honored here\n\n# after\n*.sink.rolling.roll-offset-interval-millis=30000","handlingStrategy":"validation","validationCode":"int v = Integer.parseInt(properties.getProperty(\"roll-offset-interval-millis\", \"30000\"));\nif (v < 0) {\n  throw new IllegalArgumentException(\n      \"roll-offset-interval-millis must be non-negative (0 or absent for none), got \" + v);\n}","typeGuard":null,"tryCatchPattern":"try {\n  sink.init(subsetConf);\n} catch (MetricsException e) {\n  // message names the exact key and the offending negative value\n  LOG.error(\"{}\", e.getMessage());\n}","preventionTips":["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"],"tags":["metrics2","rolling-file-sink","configuration","range"],"backgroundTag":"config-value-out-of-range","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}