apache/seatunnel · error · IllegalStateException

schema-change checkpoint[%s] is aborted, phase: [%s]

Error message

schema-change checkpoint[%s] is aborted, phase: [%s]

What it means

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.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/flow/SourceFlowLifeCycle.java:569

    /**
     * Notifies the source reader that a checkpoint has been aborted.
     *
     * <p>Delegates to {@link SourceReader#notifyCheckpointAborted(long)} and then checks whether
     * the aborted checkpoint matches an in-progress schema-change phase. If so, an {@link
     * IllegalStateException} is thrown because a schema-change checkpoint cannot be safely retried
     * once aborted.
     *
     * @param checkpointId the ID of the aborted checkpoint
     * @throws IllegalStateException if the aborted checkpoint is a schema-change checkpoint
     * @throws Exception if the reader's abort notification hook fails
     */
    @Override
    public void notifyCheckpointAborted(long checkpointId) throws Exception {
        reader.notifyCheckpointAborted(checkpointId);
        if (schemaChangePhase.get() != null
                && schemaChangePhase.get().getCheckpointId() == checkpointId) {
            throw new IllegalStateException(
                    String.format(
                            "schema-change checkpoint[%s] is aborted, phase: [%s]",
                            checkpointId, schemaChangePhase.get().getPhase()));
        }
    }

    @Override
    public void notifyCheckpointEnd(long checkpointId) throws Exception {
        if (schemaChangePhase.get() != null
                && schemaChangePhase.get().getCheckpointId() == checkpointId) {
            log.info(
                    "notify schema-change checkpoint[{}] end, phase: [{}]",
                    checkpointId,
                    schemaChangePhase.get().getPhase());
            schemaChangePhase.set(null);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Increase checkpoint timeout and interval so schema-change checkpoints complete before abort.
2. Investigate and fix the root cause of the abort (backpressure, slow sink, network).
3. Enable/use checkpoint timeout alerts; monitor coordinator logs for abort reasons.
4. Restart the job from the last successful snapshot to clear the stuck phase.

try { pipeline.run(); } catch (IllegalStateException e) { if (e.getMessage().contains("schema-change checkpoint") && e.getMessage().contains("is aborted")) { restoreFromLastSnapshot(); } else { throw e; } }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• schema-change-after checkpoint is already completed, job id:
• schema-change checkpoint[%s,%s] and phase[%s] is not matched
• checkpointId is already set
• Unsupported alter table event:
• Unsupported alter table event:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/797dfe9e9caf20c1. Report an issue: GitHub.