apache/flink · warning · UnsupportedOperationException

This source reader does not support pausing or resuming spli

Error message

This source 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

SourceReader.pauseOrResumeSplits is a default method that throws UnsupportedOperationException unless the source overrides it. It backs watermark alignment: without the ability to pause/resume splits, splits can become 'unaligned' (their watermarks diverge beyond the allowed limit), causing unpredictable watermark behavior when a reader holds more than one split. The throw pushes source authors to implement it; the config flag lets operators opt out at their own risk.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java:163

     *
     * <p>Note that no other methods can be called in parallel, so updating subscriptions can be
     * done atomically. 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
     */
    @PublicEvolving
    default void pauseOrResumeSplits(
            Collection<String> splitsToPause, Collection<String> splitsToResume) {
        throw new UnsupportedOperationException(
                "This source 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. If it is your own Source, override pauseOrResumeSplits in your SourceReader to actually pause/resume the named splits.
2. Upgrade the source connector to a version that implements pauseOrResumeSplits.
3. Temporarily set pipeline.watermark-alignment.allow-unaligned-source-splits=true to opt out (note: deprecated and slated for removal).
4. Limit to a single split per reader as a workaround, since unaligned splits only matter with more than one split.
5. Disable watermark alignment (remove the source.watermark-alignment settings) if split pausing is unavailable.

Example fix

// before: env config with source.watermark-alignment enabled on a source whose reader doesn't implement pauseOrResumeSplits -> throws
// after (temporary opt-out):
//   config.set("pipeline.watermark-alignment.allow-unaligned-source-splits", "true");
// or implement in your reader:
//   @Override public void pauseOrResumeSplits(Collection<String> pause, Collection<String> resume) { /* ... */ }

// Detect whether the source reader actually implements pauseOrResumeSplits before enabling watermark alignment
boolean supportsPause =
    !SourceReader.class.isInstance(sourceReader)
        || java.lang.reflect.Modifier.isPublic(
            sourceReader.getClass().getMethod("pauseOrResumeSplits", Collection.class, Collection.class)
                .getModifiers());
// If false, either implement the method or set allow-unaligned-source-splits=true

// Best practice: configure opt-out only when the source lacks the method
boolean sourceImplementsPause;
try {
    sourceImplementsPause =
        !sourceReader.getClass().getMethod("pauseOrResumeSplits", Collection.class, Collection.class)
            .isDefault();
} catch (NoSuchMethodException e) {
    sourceImplementsPause = false;
}
if (!sourceImplementsPause) {
    config.set("pipeline.watermark-alignment.allow-unaligned-source-splits", "true");
}

When it happens

Trigger: Watermark alignment is enabled (source.watermark-alignment max drift/settings) and the runtime calls pauseOrResumeSplits on a SourceReader whose implementation did not override the default method.

Common situations: Using a third-party or custom Source that predates the pauseOrResumeSplits API; enabling watermark alignment on an older connector (e.g., an older Kafka source) that does not implement split pausing; writing a custom SourceReader and forgetting to override the method.

Related errors

• This split reader does not support pausing or resuming split
• Unsupported type of source, you could use DataStreamV2Source

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