apache/druid · error · UnsupportedOperationException

Supervisor does not have the feature to handoff task groups…

Error message

Supervisor does not have the feature to handoff task groups early implemented

What it means

The default StreamSupervisor.handoffTaskGroupsEarly is an unsupported-operation stub: supervisors that have not implemented early handoff throw this to signal the feature is unavailable on that supervisor type/implementation.

Solutions

Upgrade to a supervisor implementation/version that implements early handoff
Use the standard supervisor type that supports the feature, or implement the method in your custom supervisor by marking task groups ready for handoff
Avoid calling the early-handoff API on supervisors that do not advertise support

Example fix

// before
supervisor.handoffTaskGroupsEarly(groupIds); // UnsupportedOperationException
// after
if (supervisor.supportsEarlyHandoff()) {
  supervisor.handoffTaskGroupsEarly(groupIds);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// feature probe before invoking
boolean supported;
try { supervisor.getClass().getMethod("handoffTaskGroupsEarly", List.class);
      supported = !StreamSupervisor.class.getMethod("handoffTaskGroupsEarly", List.class)
                   .equals(supervisor.getClass().getMethod("handoffTaskGroupsEarly", List.class)); }
catch (NoSuchMethodException e) { supported = false; }

Type guard

static boolean supportsEarlyHandoff(StreamSupervisor s) {
  try {
    return !StreamSupervisor.class.getMethod("handoffTaskGroupsEarly", List.class)
        .getDeclaringClass().equals(s.getClass().getMethod("handoffTaskGroupsEarly", List.class).getDeclaringClass());
  } catch (NoSuchMethodException e) { return false; }
}

Try / catch

try {
  supervisor.handoffTaskGroupsEarly(groupIds);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("handoff task groups early")) {
    log.warn("Supervisor " + supervisor.getClass().getSimpleName() + " does not support early handoff; waiting for natural handoff");
  } else { throw e; }
}

Prevention

Check supervisor type capabilities before calling early-handoff APIs
Pin to a Druid version whose supervisors support early handoff if you rely on it
For custom supervisors, override handoffTaskGroupsEarly rather than inheriting the stub
Handle UnsupportedOperationException gracefully in automation calling this API

When it happens

Trigger: Calling handoffTaskGroupsEarly(taskGroupIds) (e.g. via the supervisor API to force early handoff) on a supervisor implementation that does not override the default method.

Common situations: Invoking early-handoff endpoints against supervisor types lacking the feature; upgrading/using a custom supervisor that never implemented the default interface method introduced later.

Related errors

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/indexing/overlord/supervisor/StreamSupervisor.java:70

   * @param checkpointMetadata metadata for the sequence to currently checkpoint
   */
  void checkpoint(int taskGroupId, DataSourceMetadata checkpointMetadata);

  /**
   * Computes maxLag, totalLag and avgLag
   */
  LagStats computeLagStats();

  int getActiveTaskGroupsCount();

  /**
   * Marks the given task groups as ready for segment hand-off irrespective of the task run times.
   * In the subsequent run, the supervisor initiates segment publish and hand-off for these task groups and rolls over their tasks.
   * taskGroupIds that are not valid or not actively reading are simply ignored.
   */
  default void handoffTaskGroupsEarly(List<Integer> taskGroupIds)
  {
    throw new UnsupportedOperationException("Supervisor does not have the feature to handoff task groups early implemented");
  }
}

View on GitHub (pinned to 9b90983fd2)