apache/seatunnel · error · UnsupportedOperationException

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

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.

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.

Appendix: 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)