{"record":{"id":"eec61a7d558ee10a","repo":"apache/flink","slug":"this-source-reader-does-not-support-pausing-or-res","errorCode":null,"errorMessage":"This source 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 source 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":"warning","filePath":"flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java","lineNumber":163,"sourceCode":"     *\n     * <p>Note that no other methods can be called in parallel, so updating subscriptions can be\n     * done atomically. This method is simply providing connectors with more expressive APIs the\n     * 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    @PublicEvolving\n    default void pauseOrResumeSplits(\n            Collection<String> splitsToPause, Collection<String> splitsToResume) {\n        throw new UnsupportedOperationException(\n                \"This source 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":145,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java#L145-L173","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If it is your own Source, override pauseOrResumeSplits in your SourceReader to actually pause/resume the named splits.","Upgrade the source connector to a version that implements pauseOrResumeSplits.","Temporarily set pipeline.watermark-alignment.allow-unaligned-source-splits=true to opt out (note: deprecated and slated for removal).","Limit to a single split per reader as a workaround, since unaligned splits only matter with more than one split.","Disable watermark alignment (remove the source.watermark-alignment settings) if split pausing is unavailable."],"exampleFix":"// before: env config with source.watermark-alignment enabled on a source whose reader doesn't implement pauseOrResumeSplits -> throws\n// after (temporary opt-out):\n//   config.set(\"pipeline.watermark-alignment.allow-unaligned-source-splits\", \"true\");\n// or implement in your reader:\n//   @Override public void pauseOrResumeSplits(Collection<String> pause, Collection<String> resume) { /* ... */ }","handlingStrategy":"fallback","validationCode":"// Detect whether the source reader actually implements pauseOrResumeSplits before enabling watermark alignment\nboolean supportsPause =\n    !SourceReader.class.isInstance(sourceReader)\n        || java.lang.reflect.Modifier.isPublic(\n            sourceReader.getClass().getMethod(\"pauseOrResumeSplits\", Collection.class, Collection.class)\n                .getModifiers());\n// If false, either implement the method or set allow-unaligned-source-splits=true","typeGuard":null,"tryCatchPattern":"// Best practice: configure opt-out only when the source lacks the method\nboolean sourceImplementsPause;\ntry {\n    sourceImplementsPause =\n        !sourceReader.getClass().getMethod(\"pauseOrResumeSplits\", Collection.class, Collection.class)\n            .isDefault();\n} catch (NoSuchMethodException e) {\n    sourceImplementsPause = false;\n}\nif (!sourceImplementsPause) {\n    config.set(\"pipeline.watermark-alignment.allow-unaligned-source-splits\", \"true\");\n}","preventionTips":["When writing a custom SourceReader, always override pauseOrResumeSplits.","Before enabling watermark alignment, confirm the connector version supports split pausing.","Treat allow-unaligned-source-splits=true as a temporary migration flag, not a permanent setting.","Prefer a single split per reader when split pausing is unavailable."],"tags":["source","watermark-alignment","source-api"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}