apache/druid · error · DruidException

INVALID_INPUT

INVALID_INPUT

Error message

'druid.coordinator.kill.%s.durationToRetain'[%s] must be 0 milliseconds or higher

What it means

validateKillConfig() requires druid.coordinator.kill.<type>.durationToRetain to be non-null and >= 0 milliseconds. This duration controls how long objects (e.g. pending segments) are retained before being killed; a negative value is invalid operator input. Note the subsequent check additionally rejects values exceeding the current epoch time in milliseconds.

Solutions

Set druid.coordinator.kill.<type>.durationToRetain to a non-negative duration (e.g. PT24H, or 0 to retain nothing)
Remove the property to use its default instead of supplying null explicitly
Restart the Coordinator after correction

Example fix

// before
druid.coordinator.kill.pendingSegments.durationToRetain=PT-24H
// after
druid.coordinator.kill.pendingSegments.durationToRetain=PT24H

Defensive patterns

Strategy: validation

Validate before calling

String raw = props.getProperty("druid.coordinator.kill.pendingSegments.durationToRetain");
if (raw != null) {
  long ms = Period.parse(raw).toStandardDuration().getMillis();
  if (ms < 0) throw new IllegalArgumentException("durationToRetain must be 0 or higher");
}

Try / catch

try {
  coordinator.start();
} catch (Exception e) {
  if (String.valueOf(e.getMessage()).contains("durationToRetain")) {
    // set a non-negative duration (e.g. PT24H) and restart
  }
}

Prevention

Never express retention as a negative duration; 0 means retain nothing
Use ISO-8601 durations (PT24H, P7D) rather than raw signed numbers
Omit the property to accept defaults instead of passing explicit nulls
Review kill.* diffs in config PRs before merge

When it happens

Trigger: Coordinator startup when config.getDurationToRetain() is null or negative for any kill config under druid.coordinator.kill.<type> (e.g. durationToRetain=-PT24H or a negative number).

Common situations: Misunderstanding the property as a negative 'grace period'; hand-editing durations to negative values to try to disable retention; missing default in a config template leaving the field null.

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

Appendix: source

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

  {
    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
      );
    }
  }

  private static DruidException newInvalidInputExceptionForOperator(String msgFormat, Object... args)
  {
    return DruidException.forPersona(DruidException.Persona.OPERATOR)
                         .ofCategory(DruidException.Category.INVALID_INPUT)
                         .build(msgFormat, args);
  }

View on GitHub (pinned to 9b90983fd2)