{"record":{"id":"797dfe9e9caf20c1","repo":"apache/seatunnel","slug":"schema-change-checkpoint-s-is-aborted-phase","errorCode":null,"errorMessage":"schema-change checkpoint[%s] is aborted, phase: [%s]","messagePattern":"schema-change checkpoint\\[(.+?)\\] is aborted, phase: \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/flow/SourceFlowLifeCycle.java","lineNumber":569,"sourceCode":"\n    /**\n     * Notifies the source reader that a checkpoint has been aborted.\n     *\n     * <p>Delegates to {@link SourceReader#notifyCheckpointAborted(long)} and then checks whether\n     * the aborted checkpoint matches an in-progress schema-change phase. If so, an {@link\n     * IllegalStateException} is thrown because a schema-change checkpoint cannot be safely retried\n     * once aborted.\n     *\n     * @param checkpointId the ID of the aborted checkpoint\n     * @throws IllegalStateException if the aborted checkpoint is a schema-change checkpoint\n     * @throws Exception if the reader's abort notification hook fails\n     */\n    @Override\n    public void notifyCheckpointAborted(long checkpointId) throws Exception {\n        reader.notifyCheckpointAborted(checkpointId);\n        if (schemaChangePhase.get() != null\n                && schemaChangePhase.get().getCheckpointId() == checkpointId) {\n            throw new IllegalStateException(\n                    String.format(\n                            \"schema-change checkpoint[%s] is aborted, phase: [%s]\",\n                            checkpointId, schemaChangePhase.get().getPhase()));\n        }\n    }\n\n    @Override\n    public void notifyCheckpointEnd(long checkpointId) throws Exception {\n        if (schemaChangePhase.get() != null\n                && schemaChangePhase.get().getCheckpointId() == checkpointId) {\n            log.info(\n                    \"notify schema-change checkpoint[{}] end, phase: [{}]\",\n                    checkpointId,\n                    schemaChangePhase.get().getPhase());\n            schemaChangePhase.set(null);\n        }\n    }\n","sourceCodeStart":551,"sourceCodeEnd":587,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/flow/SourceFlowLifeCycle.java#L551-L587","documentation":"notifyCheckpointAborted() in SourceFlowLifeCycle throws IllegalStateException when the aborted checkpoint is exactly the checkpointId bound to the active schema-change phase. Losing that checkpoint means the schema-change barrier can never complete, leaving the source in an intermediate schema-change state the pipeline cannot resolve.","triggerScenarios":"The CheckpointCoordinator aborts (expires/fails) the checkpoint whose id equals schemaChangePhase.getCheckpointId() while schemaChangePhase is non-null — i.e. abort happens between phase creation and barrier alignment/completion.","commonSituations":"Checkpoint timeouts caused by backpressure or slow sinks while a schema-change barrier is pending; master node failover aborting in-flight checkpoints; checkpoint interval too short for large state.","solutions":["Increase checkpoint timeout and interval so schema-change checkpoints complete before abort.","Investigate and fix the root cause of the abort (backpressure, slow sink, network).","Enable/use checkpoint timeout alerts; monitor coordinator logs for abort reasons.","Restart the job from the last successful snapshot to clear the stuck phase."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { pipeline.run(); } catch (IllegalStateException e) { if (e.getMessage().contains(\"schema-change checkpoint\") && e.getMessage().contains(\"is aborted\")) { restoreFromLastSnapshot(); } else { throw e; } }","preventionTips":["Tune checkpoint timeout larger than worst-case barrier alignment time","Reduce backpressure so schema-change checkpoints complete on schedule","Monitor coordinator abort events and alert"],"tags":["checkpoint","schema-change","abort","timeout"],"backgroundTag":"invalid-state-transition","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}