apache/iceberg · error · IllegalArgumentException

Received unknown event from subtask %d: %s

Error message

Received unknown event from subtask %d: %s

What it means

AbstractIcebergEnumerator.handleSourceEvent expects either a SplitRequestEvent (finished split ids + hostname) or an AddSplitBackEvent (waitLikeContinuous). Any other SourceEvent arriving from a subtask is unknown to the Iceberg protocol, and the enumerator throws IllegalArgumentException with the event's canonical class name and the subtask id. This guards against reader/enumerator protocol mismatches.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/AbstractIcebergEnumerator.java:95

    // Iceberg source uses custom split request event to piggyback finished split ids.
    throw new UnsupportedOperationException(
        String.format(
            Locale.ROOT,
            "Received invalid default split request event "
                + "from subtask %d as Iceberg source uses custom split request event",
            subtaskId));
  }

  @Override
  public void handleSourceEvent(int subtaskId, SourceEvent sourceEvent) {
    if (sourceEvent instanceof SplitRequestEvent) {
      SplitRequestEvent splitRequestEvent = (SplitRequestEvent) sourceEvent;
      LOG.info("Received request split event from subtask {}", subtaskId);
      assigner.onCompletedSplits(splitRequestEvent.finishedSplitIds());
      readersAwaitingSplit.put(subtaskId, splitRequestEvent.requesterHostname());
      assignSplits();
    } else {
      throw new IllegalArgumentException(
          String.format(
              Locale.ROOT,
              "Received unknown event from subtask %d: %s",
              subtaskId,
              sourceEvent.getClass().getCanonicalName()));
    }
  }

  // Flink's SourceCoordinator already keeps track of subTask to splits mapping.
  // It already takes care of re-assigning splits to speculated attempts as well.
  @Override
  public void handleSourceEvent(int subTaskId, int attemptNumber, SourceEvent sourceEvent) {
    handleSourceEvent(subTaskId, sourceEvent);
  }

  @Override
  public void addSplitsBack(List<IcebergSourceSplit> splits, int subtaskId) {
    LOG.info("Add {} splits back to the pool for failed subtask {}", splits.size(), subtaskId);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Ensure all TaskManagers run the same iceberg-flink runtime version — re-build/redeploy a consistent job jar.
2. Check for custom SourceEvent subclasses in your code; route them through the enumerator or convert them to SplitRequestEvent.
3. Inspect the class name in the message to identify which component sent the unknown event and fix that sender.
4. If you extended the protocol, override handleSourceEvent to accept your event before falling back to super.

Example fix

// before
@Override
public void handleSourceEvent(int subtaskId, SourceEvent event) { super.handleSourceEvent(subtaskId, event); }
// after
@Override
public void handleSourceEvent(int subtaskId, SourceEvent event) {
  if (event instanceof MyCustomEvent) { handleCustom(subtaskId, (MyCustomEvent) event); return; }
  super.handleSourceEvent(subtaskId, event);
}

if (!(event instanceof SplitRequestEvent) && !(event instanceof AddSplitBackEvent)) {
  throw new IllegalArgumentException("Unsupported SourceEvent for Iceberg enumerator: " + event.getClass());
}

boolean isIcebergSourceEvent(SourceEvent e) { return e instanceof SplitRequestEvent || e instanceof AddSplitBackEvent; }

When it happens

Trigger: A reader sends a custom SourceEvent class (or a version-mismatched event type) to an Iceberg enumerator — e.g., a custom implementation of IcebergSourceReader emitting its own event, or mixed Iceberg versions across the cluster where event classes differ.

Common situations: Deploying mismatched Iceberg-flink reader/enumerator jars in the same job after an upgrade; custom extensions of the source that add new event types without extending the enumerator; fat-jar shading producing duplicate event classes.

Related errors

• Received unknown event from subtask %d: %s
• Unsupported status:
• Unknown serialize version:
• Unrecognized version or corrupt state: ${version}
• Unrecognized version or corrupt state: ${version}

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/0319f17b761f562d. Report an issue: GitHub.