apache/iceberg · error · IllegalArgumentException

Received unknown event from subtask %d: %s

Error message

Received unknown event from subtask %d: %s

What it means

The IcebergSource enumerator's handleSourceEvent received a SourceEvent from a reader subtask that it does not recognize. It only understands SplitRequestEvent; anything else is rejected. This typically indicates an internal protocol mismatch between reader and enumerator (e.g., mixed Iceberg connector versions on the same job).

Source

Thrown at flink/v1.20/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 and the JobManager use the exact same Iceberg Flink connector version.
2. Check for multiple iceberg-flink jars on the classpath and remove duplicates from the user jar (shade/relocate).
3. If a custom reader emits extra events, override handleSourceEvent to handle them before falling through to the default branch.

Example fix

// before
sourceReaderContext.sendSourceEvent(myCustomEvent);
// after
// only send SplitRequestEvent, or handle custom events in an enumerator subclass:
@Override
public void handleSourceEvent(int subtaskId, SourceEvent event) {
  if (event instanceof MyCustomEvent) { handleCustom((MyCustomEvent) event); return; }
  super.handleSourceEvent(subtaskId, event);
}

// Ensure consistent connector version at deployment time
String expected = "org.apache.iceberg:iceberg-flink-runtime-1.20:<version>";
String found = org.apache.iceberg.flink.IcebergFlinkVersion.class.getPackage().getImplementationVersion();
if (!expected.endsWith(found)) throw new IllegalStateException("Connector version mismatch: " + found);

When it happens

Trigger: A SourceReader sends a custom/unknown SourceEvent to the enumerator via the split enumerator context, and handleSourceEvent is called with an event that is not a SplitRequestEvent.

Common situations: Running mismatched Iceberg Flink connector jar versions between JobManager and TaskManagers; custom reader subclasses emitting their own events; classpath contamination with two connector versions.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• Unsupported status:
• Received unknown event from subtask %d: %s
• Invalid operator event type:
• Unsupported version:
• Source table %s contains one/all of the reserved property ke

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