apache/flink · error · UnsupportedOperationException

This split reader does not support pausing or resuming split

Error message

This split reader does not support pausing or resuming splits which can lead to unaligned splits.
Unaligned splits are splits where the output watermarks of the splits have diverged more than the allowed limit.
It is highly discouraged to use unaligned source splits, as this leads to unpredictable
watermark alignment if there is more than a single split per reader. It is recommended to implement pausing splits
for this source. At your own risk, you can allow unaligned source splits by setting the
configuration parameter `pipeline.watermark-alignment.allow-unaligned-source-splits' to true.
Beware that this configuration parameter will be dropped in a future Flink release.

What it means

The default SplitReader#pauseOrResumeSplits throws UnsupportedOperationException. It is invoked by the framework during watermark alignment when a source reads more than one split per reader, unless the source implements split pausing or the user explicitly allows unaligned source splits via pipeline.watermark-alignment.allow-unaligned-source-splits=true. The default will be removed in a future release.

Source

Thrown at flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/reader/splitreader/SplitReader.java:92

     * Pauses or resumes reading of individual splits readers.
     *
     * <p>Note that no other methods can be called in parallel, so it's fine to non-atomically
     * update subscriptions. This method is simply providing connectors with more expressive APIs
     * the opportunity to update all subscriptions at once.
     *
     * <p>This is currently used to align the watermarks of splits, if watermark alignment is used
     * and the source reads from more than one split.
     *
     * <p>The default implementation throws an {@link UnsupportedOperationException} where the
     * default implementation will be removed in future releases. To be compatible with future
     * releases, it is recommended to implement this method and override the default implementation.
     *
     * @param splitsToPause the splits to pause
     * @param splitsToResume the splits to resume
     */
    default void pauseOrResumeSplits(
            Collection<SplitT> splitsToPause, Collection<SplitT> splitsToResume) {
        throw new UnsupportedOperationException(
                "This split reader does not support pausing or resuming splits which can lead to unaligned splits.\n"
                        + "Unaligned splits are splits where the output watermarks of the splits have diverged more than the allowed limit.\n"
                        + "It is highly discouraged to use unaligned source splits, as this leads to unpredictable\n"
                        + "watermark alignment if there is more than a single split per reader. It is recommended to implement pausing splits\n"
                        + "for this source. At your own risk, you can allow unaligned source splits by setting the\n"
                        + "configuration parameter `pipeline.watermark-alignment.allow-unaligned-source-splits' to true.\n"
                        + "Beware that this configuration parameter will be dropped in a future Flink release.");
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Implement pauseOrResumeSplits in your SplitReader so the connector can pause/resume the given splits to keep watermarks aligned.
2. If you accept the risk, set pipeline.watermark-alignment.allow-unaligned-source-splits=true (note: slated for removal in a future Flink).
3. Reduce to a single split per reader so alignment pausing is not required.
4. Disable watermark alignment if the source cannot support pausing.

Example fix

// before: default impl throws
@Override
public void pauseOrResumeSplits(Collection<SplitT> pause, Collection<SplitT> resume) {
    // uses default -> UnsupportedOperationException
}
// after: implement pausing for the connector
@Override
public void pauseOrResumeSplits(Collection<MySplit> pause, Collection<MySplit> resume) {
    pause.forEach(kafkaConsumer::pause);
    resume.forEach(kafkaConsumer::resume);
}

// Detect support before enabling alignment with multiple splits:
boolean supportsPause = supportsPauseOrResumeSplits(mySplitReader);
if (!supportsPause && splitsPerReader > 1 && watermarkAlignmentEnabled) {
    throw new UnsupportedOperationException(
        "SplitReader does not support pause/resume; disable alignment or allow unaligned splits");
}

static boolean supportsPauseOrResumeSplits(SplitReader<?, ?> r) {
    try {
        r.pauseOrResumeSplits(List.of(), List.of());
        return true;
    } catch (UnsupportedOperationException e) {
        return false;
    }
}

try {
    splitReader.pauseOrResumeSplits(toPause, toResume);
} catch (UnsupportedOperationException e) {
    // fall back: set pipeline.watermark-alignment.allow-unaligned-source-splits=true,
    // or reduce to one split per reader
    throw e;
}

When it happens

Trigger: Watermark alignment is configured (source.watermark.alignment.max-drift / groups) and the source has multiple splits assigned to one reader, and the concrete SplitReader does not override pauseOrResumeSplits.

Common situations: Enabling watermark alignment on a connector whose SplitReader has not implemented split pausing; multi-split sources like Kafka with alignment enabled.

Related errors

• SplitFetcher thread %d received unexpected exception while p
• Source fetch execution was interrupted
• The thread was interrupted while waiting for a fetcher task.
• One or more fetchers have encountered exception
• exception in queue future completion

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/3215e3344ccf43cb. Report an issue: GitHub.