{"record":{"id":"3215e3344ccf43cb","repo":"apache/flink","slug":"this-split-reader-does-not-support-pausing-or-resu","errorCode":null,"errorMessage":"This split reader does not support pausing or resuming splits which can lead to unaligned splits.\nUnaligned splits are splits where the output watermarks of the splits have diverged more than the allowed limit.\nIt is highly discouraged to use unaligned source splits, as this leads to unpredictable\nwatermark alignment if there is more than a single split per reader. It is recommended to implement pausing splits\nfor this source. At your own risk, you can allow unaligned source splits by setting the\nconfiguration parameter `pipeline.watermark-alignment.allow-unaligned-source-splits' to true.\nBeware that this configuration parameter will be dropped in a future Flink release.","messagePattern":"This split reader does not support pausing or resuming splits which can lead to unaligned splits\\.\nUnaligned splits are splits where the output watermarks of the splits have diverged more than the allowed limit\\.\nIt is highly discouraged to use unaligned source splits, as this leads to unpredictable\nwatermark alignment if there is more than a single split per reader\\. It is recommended to implement pausing splits\nfor this source\\. At your own risk, you can allow unaligned source splits by setting the\nconfiguration parameter `pipeline\\.watermark-alignment\\.allow-unaligned-source-splits' to true\\.\nBeware that this configuration parameter will be dropped in a future Flink release\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/reader/splitreader/SplitReader.java","lineNumber":92,"sourceCode":"     * Pauses or resumes reading of individual splits readers.\n     *\n     * <p>Note that no other methods can be called in parallel, so it's fine to non-atomically\n     * update subscriptions. This method is simply providing connectors with more expressive APIs\n     * the opportunity to update all subscriptions at once.\n     *\n     * <p>This is currently used to align the watermarks of splits, if watermark alignment is used\n     * and the source reads from more than one split.\n     *\n     * <p>The default implementation throws an {@link UnsupportedOperationException} where the\n     * default implementation will be removed in future releases. To be compatible with future\n     * releases, it is recommended to implement this method and override the default implementation.\n     *\n     * @param splitsToPause the splits to pause\n     * @param splitsToResume the splits to resume\n     */\n    default void pauseOrResumeSplits(\n            Collection<SplitT> splitsToPause, Collection<SplitT> splitsToResume) {\n        throw new UnsupportedOperationException(\n                \"This split reader does not support pausing or resuming splits which can lead to unaligned splits.\\n\"\n                        + \"Unaligned splits are splits where the output watermarks of the splits have diverged more than the allowed limit.\\n\"\n                        + \"It is highly discouraged to use unaligned source splits, as this leads to unpredictable\\n\"\n                        + \"watermark alignment if there is more than a single split per reader. It is recommended to implement pausing splits\\n\"\n                        + \"for this source. At your own risk, you can allow unaligned source splits by setting the\\n\"\n                        + \"configuration parameter `pipeline.watermark-alignment.allow-unaligned-source-splits' to true.\\n\"\n                        + \"Beware that this configuration parameter will be dropped in a future Flink release.\");\n    }\n}\n","sourceCodeStart":74,"sourceCodeEnd":102,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/reader/splitreader/SplitReader.java#L74-L102","documentation":"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.","triggerScenarios":"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.","commonSituations":"Enabling watermark alignment on a connector whose SplitReader has not implemented split pausing; multi-split sources like Kafka with alignment enabled.","solutions":["Implement pauseOrResumeSplits in your SplitReader so the connector can pause/resume the given splits to keep watermarks aligned.","If you accept the risk, set pipeline.watermark-alignment.allow-unaligned-source-splits=true (note: slated for removal in a future Flink).","Reduce to a single split per reader so alignment pausing is not required.","Disable watermark alignment if the source cannot support pausing."],"exampleFix":"// before: default impl throws\n@Override\npublic void pauseOrResumeSplits(Collection<SplitT> pause, Collection<SplitT> resume) {\n    // uses default -> UnsupportedOperationException\n}\n// after: implement pausing for the connector\n@Override\npublic void pauseOrResumeSplits(Collection<MySplit> pause, Collection<MySplit> resume) {\n    pause.forEach(kafkaConsumer::pause);\n    resume.forEach(kafkaConsumer::resume);\n}","handlingStrategy":"validation","validationCode":"// Detect support before enabling alignment with multiple splits:\nboolean supportsPause = supportsPauseOrResumeSplits(mySplitReader);\nif (!supportsPause && splitsPerReader > 1 && watermarkAlignmentEnabled) {\n    throw new UnsupportedOperationException(\n        \"SplitReader does not support pause/resume; disable alignment or allow unaligned splits\");\n}\n\nstatic boolean supportsPauseOrResumeSplits(SplitReader<?, ?> r) {\n    try {\n        r.pauseOrResumeSplits(List.of(), List.of());\n        return true;\n    } catch (UnsupportedOperationException e) {\n        return false;\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    splitReader.pauseOrResumeSplits(toPause, toResume);\n} catch (UnsupportedOperationException e) {\n    // fall back: set pipeline.watermark-alignment.allow-unaligned-source-splits=true,\n    // or reduce to one split per reader\n    throw e;\n}","preventionTips":["Implement pauseOrResumeSplits for any connector that may use watermark alignment.","Do not enable alignment on a source known to lack split pausing.","Track that pipeline.watermark-alignment.allow-unaligned-source-splits will be removed; do not build long-term on it."],"tags":["watermark-alignment","split-reader","config","flink-source"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}