apache/druid · error · DruidException

'druid.coordinator.kill.maxSegments

Error message

'druid.coordinator.kill.maxSegments'[%s] must be a positive integer.

What it means

validateKillConfigs() requires druid.coordinator.kill.maxSegments to be a non-negative value, throwing this invalid-input error at Coordinator startup when it is negative. The property caps how many unused segments are deleted per kill-task run, so a negative cap is nonsensical.

Solutions

Set druid.coordinator.kill.maxSegments to a positive integer (e.g. 100)
To effectively disable segment killing, set a very large maxSegments and/or set druid.coordinator.kill.period to a very large value instead of a negative number
Restart the Coordinator once the property is corrected

Example fix

// before
druid.coordinator.kill.maxSegments=-1
// after
druid.coordinator.kill.maxSegments=100

Defensive patterns

Strategy: validation

Validate before calling

final int maxSegments = Integer.parseInt(props.getProperty("druid.coordinator.kill.maxSegments", "100"));
if (maxSegments < 0) {
  throw new IllegalArgumentException("druid.coordinator.kill.maxSegments must be a positive integer");
}

Try / catch

try {
  coordinator.start();
} catch (Exception e) {
  if (String.valueOf(e.getMessage()).contains("kill.maxSegments")) {
    // set a positive integer and restart
  }
}

Prevention

Never use negative values to 'disable' killing; use large values or disable via period instead
Add pre-deploy config validation for kill.* properties
Keep defaults (100) unless there is a measured need to change
Sanitize numeric properties with a linting script before rollout

When it happens

Trigger: Coordinator startup when killUnusedConfig.getMaxSegments() < 0, i.e. druid.coordinator.kill.maxSegments (or the legacy druid.coordinator.kill.maxSegments property feeding KillUnusedSegmentsConfig) is set to a negative integer.

Common situations: Typo like -100 instead of 100, or an operator disabling killing by supplying a negative number expecting it to be treated as 'disabled' (use a very large value or the dedicated kill switch instead).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/d6cdecaa90b97fee. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/server/coordinator/config/DruidCoordinatorConfig.java:111

    validateKillConfig(killConfigs.auditLogs(), "audit");
    validateKillConfig(killConfigs.compactionConfigs(), "compaction");
    validateKillConfig(killConfigs.datasources(), "datasource");
    validateKillConfig(killConfigs.rules(), "rule");
    validateKillConfig(killConfigs.supervisors(), "supervisor");
    validateKillConfig(killConfigs.segmentSchemas(), "segmentSchema");

    // Validate config for killing unused segments
    final KillUnusedSegmentsConfig killUnusedConfig
        = killConfigs.unusedSegments(getCoordinatorIndexingPeriod());
    if (killUnusedConfig.getCleanupPeriod().getMillis() < getCoordinatorIndexingPeriod().getMillis()) {
      throw newInvalidInputExceptionForOperator(
          "'druid.coordinator.kill.period'[%s] must be greater than or equal to"
          + " 'druid.coordinator.period.indexingPeriod'[%s]",
          killUnusedConfig.getCleanupPeriod(), getCoordinatorIndexingPeriod()
      );
    }
    if (killUnusedConfig.getMaxSegments() < 0) {
      throw newInvalidInputExceptionForOperator(
          "'druid.coordinator.kill.maxSegments'[%s] must be a positive integer.",
          killUnusedConfig.getMaxSegments()
      );
    }
  }

  private void validateKillConfig(MetadataCleanupConfig config, String propertyPrefix)
  {
    if (!config.isCleanupEnabled()) {
      // Do not perform validation if cleanup is disabled
      return;
    }

    final Duration metadataManagementPeriod = getCoordinatorMetadataStoreManagementPeriod();
    final Duration period = config.getCleanupPeriod();
    if (period == null || period.getMillis() < metadataManagementPeriod.getMillis()) {
      throw newInvalidInputExceptionForOperator(
          "'druid.coordinator.kill.%s.period'[%s] must be greater than"

View on GitHub (pinned to 9b90983fd2)