apache/seatunnel · error · IllegalStateException

schema-change checkpoint

Error message

schema-change checkpoint[%s,%s] and phase[%s] is not matched

What it means

In SourceFlowLifeCycle.triggerBarrier(), when a barrier of schema-change type arrives, the engine verifies that the barrier's checkpoint type matches the currently recorded SchemaChangePhase (before-checkpoint pairs with before-phase, after with after). A mismatch means the phase recorded on the source path does not correspond to the barrier the coordinator sent, so an IllegalStateException is thrown.

Solutions

1. Restart the affected task so phase state and barrier stream resynchronize.
2. Check logs for an earlier failed triggerSchemaChangeBefore/AfterCheckpoint that left the wrong phase set.
3. Verify all nodes run the same SeaTunnel version (rolling-upgrade mixing of checkpoint semantics).
4. Retry the job from the last consistent checkpoint/snapshot.

// verify phase matches barrier type before trigger
boolean matched = (checkpointType.isSchemaChangeBeforeCheckpoint() && phase.isBeforePhase()) || (checkpointType.isSchemaChangeAfterCheckpoint() && phase.isAfterPhase());

try { triggerBarrier(barrier); } catch (IllegalStateException e) { if (e.getMessage().contains("is not matched")) { restartTaskToResyncPhase(); } else { throw e; } }

When it happens

Trigger: triggerBarrier() receives a checkpointType.isSchemaChangeBeforeCheckpoint() barrier while phase is after-phase (or vice versa), or any schema-change-typed barrier while schemaChangePhase is null/mismatched.

Common situations: Checkpoint type/phase bookkeeping desynchronization after a failed or retried schema-change checkpoint; barrier reordering after task restart or recovery from an older checkpoint id; mixed engine/connector versions during rolling upgrade.

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

• checkpointId is already set
• schema-change-after checkpoint is already completed, job id
• schema-change checkpoint
• ACKNOWLEDGE_FAILED
• ACKNOWLEDGE_FAILED

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

Appendix: source

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

        }

        log.debug(
                "trigger barrier [{}] finished, cost: {}ms. taskLocation: [{}]",
                barrier.getId(),
                System.currentTimeMillis() - startTime,
                currentTaskLocation);

        CheckpointType checkpointType = ((CheckpointBarrier) barrier).getCheckpointType();
        if (checkpointType.isSchemaChangeCheckpoint()) {
            if (schemaChanging()) {
                if (checkpointType.isSchemaChangeBeforeCheckpoint()
                        && schemaChangePhase.get().isBeforePhase()) {
                    schemaChangePhase.get().setCheckpointId(barrier.getId());
                } else if (checkpointType.isSchemaChangeAfterCheckpoint()
                        && schemaChangePhase.get().isAfterPhase()) {
                    schemaChangePhase.get().setCheckpointId(barrier.getId());
                } else {
                    throw new IllegalStateException(
                            String.format(
                                    "schema-change checkpoint[%s,%s] and phase[%s] is not matched",
                                    barrier.getId(),
                                    checkpointType,
                                    schemaChangePhase.get().getPhase()));
                }
                log.info(
                        "lock checkpoint[{}] waiting for complete..., phase: [{}]",
                        barrier.getId(),
                        schemaChangePhase.get().getPhase());
            } else {
                log.debug(
                        "Ignore schema-change checkpoint[{}] on idle task, phase: [{}]",
                        barrier.getId(),
                        checkpointType);
            }
        }
    }

View on GitHub (pinned to cf67b549a7)