apache/seatunnel · error · ClickhouseConnectorException

Unsupported handleSplitRequest: %d

Error message

Unsupported handleSplitRequest: %d

What it means

ClickhouseSourceSplitEnumerator does not support on-demand split requests from readers: readers receive splits via assignment in handleSplitRequest's place, so any reader that calls handleSplitRequest(subtaskId) triggers this UNSUPPORTED_OPERATION exception. It is an internal-protocol guard, not a data error.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/split/ClickhouseSourceSplitEnumerator.java:144

                assignSplit(Collections.singletonList(subtaskId));
            } else {
                LOG.warn(
                        "Reader {} is not registered. Pending splits {} are not assigned.",
                        subtaskId,
                        splits);
            }
        }
        LOG.info("Add back splits {} to JdbcSourceSplitEnumerator.", splits.size());
    }

    @Override
    public int currentUnassignedSplitSize() {
        return this.pendingSplit.size();
    }

    @Override
    public void handleSplitRequest(int subtaskId) {
        throw new ClickhouseConnectorException(
                CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION,
                String.format("Unsupported handleSplitRequest: %d", subtaskId));
    }

    @Override
    public void registerReader(int subtaskId) {
        LOG.info("Register reader {} to ClickhouseSourceSplitEnumerator.", subtaskId);
        if (!pendingSplit.isEmpty()) {
            synchronized (stateLock) {
                assignSplit(Collections.singletonList(subtaskId));
            }
        }
    }

    @Override
    public ClickhouseSourceState snapshotState(long checkpointId) throws Exception {
        synchronized (stateLock) {
            return new ClickhouseSourceState(shouldEnumerate, pendingSplit);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Don't call handleSplitRequest from reader code; rely on the enumerator's push-based addSplitBack/assignSplit flow.
2. Ensure the source reader's handledSplitsWithSnapshotEnd/ noMoreElement logic signals completion instead of requesting new splits.
3. If running under Flink/Spark translation, verify the connector version matches the translation module version.
4. Report as a bug if stock reader code triggers it during a normal parallel read.

Example fix

// before: reader requesting splits
context.sendSplitRequest();
// after: wait for enumerator-pushed assignment
// (remove sendSplitRequest call; splits arrive automatically via addSplits)

// Only rely on push-based assignment; verify enumerator type before requesting
if (!(splitEnumerator instanceof ClickhouseSourceSplitEnumerator)) {
  context.sendSplitRequest(); // safe only for request-capable enumerators
}

boolean supportsSplitRequests(SourceSplitEnumerator<?, ?> e) {
  return !(e instanceof ClickhouseSourceSplitEnumerator);
}

try {
  enumerator.handleSplitRequest(subtaskId);
} catch (ClickhouseConnectorException e) {
  if (e.getSeaTunnelErrorCode() == CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION) {
    // fall back to push-based assignment; don't retry the request
  } else throw e;
}

When it happens

Trigger: A SourceReader registered via registerReader then issues a split request to the enumerator (e.g. reader requests more splits after finishing its batch), which this enumerator's implementation always rejects with String.format("Unsupported handleSplitRequest: %d", subtaskId).

Common situations: Engine/source combination that uses the request-response split assignment protocol instead of the push model; running this connector on a translation layer (Flink/Spark) whose readers proactively request splits; custom reader code calling handleSplitRequest directly.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported rowKind: " + rowKind
• UNSUPPORTED_OPERATION
• A decoding format must override this method to apply metadat
• Unsupported convert %s to %s
• Unsupported convert ${value.getClass()} to Float, typeDefine

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/e90fedf57926fa58. Report an issue: GitHub.