apache/druid · error · DruidException

'druid.coordinator.kill.

Error message

'druid.coordinator.kill.%s.period'[%s] must be greater than 'druid.coordinator.period.metadataStoreManagementPeriod'[%s]

What it means

validateKillConfig() (applied per kill target such as unusedSegments, pendingSegments, segments meta schemas) enforces that each druid.coordinator.kill.<type>.period is strictly greater than druid.coordinator.period.metadataStoreManagementPeriod, because these cleanup duties are scheduled relative to that management period. A missing period, or one less than/equal to the management period, is rejected as invalid operator input.

Solutions

Set druid.coordinator.kill.<type>.period strictly greater than druid.coordinator.period.metadataStoreManagementPeriod (e.g. management PT1H, kill period P1D)
Or lower druid.coordinator.period.metadataStoreManagementPeriod below the desired kill period
Restart the Coordinator after updating runtime.properties

Example fix

// before
druid.coordinator.period.metadataStoreManagementPeriod=PT2H
druid.coordinator.kill.pendingSegments.period=PT1H
// after
druid.coordinator.period.metadataStoreManagementPeriod=PT1H
druid.coordinator.kill.pendingSegments.period=P1D

Defensive patterns

Strategy: validation

Validate before calling

final Period mgmt = Period.parse(props.getProperty("druid.coordinator.period.metadataStoreManagementPeriod", "P1D"));
for (String type : List.of("unusedSegments", "pendingSegments", "segmentSchema")) {
  String p = props.getProperty("druid.coordinator.kill." + type + ".period");
  if (p != null && Period.parse(p).toStandardDuration().getMillis() <= mgmt.toStandardDuration().getMillis()) {
    throw new IllegalArgumentException(type + " kill period must be greater than metadataStoreManagementPeriod");
  }
}

Try / catch

try {
  coordinator.start();
} catch (Exception e) {
  if (String.valueOf(e.getMessage()).contains("metadataStoreManagementPeriod")) {
    // raise the offending druid.coordinator.kill.<type>.period and restart
  }
}

Prevention

Check every druid.coordinator.kill.<type>.period against metadataStoreManagementPeriod on upgrade
Treat metadataStoreManagementPeriod as the scheduling base for all kill duties
Prefer daily (P1D) kill periods with default management period
Validate coordinator runtime.properties in CI before rollout

When it happens

Trigger: Coordinator startup where any kill config's cleanupPeriod is null or its millis < metadataStoreManagementPeriod millis, e.g. druid.coordinator.kill.pendingSegments.period=PT1H while druid.coordinator.period.metadataStoreManagementPeriod=PT2H.

Common situations: Setting per-type kill periods independently without checking metadataStoreManagementPeriod; upgrading Druid where the metadataStoreManagementPeriod default changed; copy-pasting kill configs from clusters with different management periods.

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/3c073a13363a453c. Report an issue: GitHub.

Appendix: source

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

    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"
          + " 'druid.coordinator.period.metadataStoreManagementPeriod'[%s]",
          propertyPrefix, period, metadataManagementPeriod
      );
    }

    final Duration retainDuration = config.getDurationToRetain();
    if (retainDuration == null || retainDuration.getMillis() < 0) {
      throw newInvalidInputExceptionForOperator(
          "'druid.coordinator.kill.%s.durationToRetain'[%s] must be 0 milliseconds or higher",
          propertyPrefix, retainDuration
      );
    }
    if (retainDuration.getMillis() > System.currentTimeMillis()) {
      throw newInvalidInputExceptionForOperator(
          "'druid.coordinator.kill.%s.durationToRetain'[%s] cannot be greater than current time in milliseconds",
          propertyPrefix, retainDuration
      );

View on GitHub (pinned to 9b90983fd2)