apache/seatunnel · error · UnsupportedOperationException

The single-split reader don't support reading multiple split

Error message

The single-split reader don't support reading multiple splits

What it means

AbstractSingleSplitReader.addSplits enforces that a single-split (non-parallel) source is only ever given exactly one split at restore time; more than one raises UnsupportedOperationException. The class is designed for sources that produce exactly one ReaderSplit, so restoring multiple splits is a programming/config error.

Source

Thrown at seatunnel-connectors-v2/connector-common/src/main/java/org/apache/seatunnel/connectors/seatunnel/common/source/AbstractSingleSplitReader.java:57

        }
    }

    public void internalPollNext(Collector<T> output) throws Exception {}

    @Override
    public final List<SingleSplit> snapshotState(long checkpointId) throws Exception {
        return Collections.singletonList(new SingleSplit(snapshotStateToBytes(checkpointId)));
    }

    protected byte[] snapshotStateToBytes(long checkpointId) throws Exception {
        // default nothing
        return null;
    }

    @Override
    public final void addSplits(List<SingleSplit> splits) {
        if (splits.size() > 1) {
            throw new UnsupportedOperationException(
                    "The single-split reader don't support reading multiple splits");
        }
        byte[] restoredState = splits.get(0).getState();
        if (restoredState != null && restoredState.length > 0) {
            restoreState(restoredState);
        }
    }

    protected void restoreState(byte[] restoredState) {
        // default nothing
    }

    @Override
    public final void handleNoMoreSplits() {
        // nothing
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Ensure the source's split enumerator returns exactly one split when the reader extends AbstractSingleSplitReader.
  2. Restore the job with the same parallelism/settings it was checkpointed with, or start a fresh (non-restored) job.
  3. If the source genuinely needs multiple splits, implement a parallel reader (SourceReader with normal split handling) instead of the single-split base.
  4. Update all nodes to the same SeaTunnel/connector version so enumerator and reader behavior match.
Defensive patterns

Strategy: validation

Validate before calling

// before submitting/restoring, confirm the source yields a single split
List<SingleSplit> splits = enumerator.enumerateSplits();
if (splits.size() != 1) {
    throw new IllegalStateException("single-split source must yield exactly 1 split, got " + splits.size());
}

Try / catch

try {
    reader.addSplits(splits);
} catch (UnsupportedOperationException e) {
    LOG.error("single-split reader got {} splits", splits.size());
    // fail the restore with a clear parallelism/config message
    throw e;
}

Prevention

When it happens

Trigger: Job restoration (addSplits called by the framework) delivering more than one SingleSplit to a reader extending AbstractSingleSplitReader — e.g. the split enumerator wrongly returned multiple splits for a source configured as single-split, or a saved checkpoint from a different parallelism is being restored.

Common situations: Changing source parallelism/dag-parsing so the enumerator emits several splits while the reader is still the single-split base class; mixing connector versions between a checkpoint and its restore; a custom Source whose SourceSplitEnumerator returns multiple splits but whose reader extends AbstractSingleSplitReader.

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

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