What causes "Unknown checkpoint type: " in apache/seatunnel?

Use one of the exact enum names accepted by CheckpointType (check the enum constants in CheckpointType.java) with correct case.

apache/seatunnel · error · IllegalArgumentException

Unknown checkpoint type:

Error message

Unknown checkpoint type:

What it means

CheckpointType.fromName converts a checkpoint type name string (e.g. from job config) into the CheckpointType enum; when no enum constant's name matches the input it throws an IllegalArgumentException. Valid names are the enum constants such as 'checkpoint'/'savepoint' style types defined in CheckpointType.

Source

Thrown at seatunnel-engine/seatunnel-engine-core/src/main/java/org/apache/seatunnel/engine/core/checkpoint/CheckpointType.java:46

    /** Automatically triggered by the schema change. */
    SCHEMA_CHANGE_AFTER_POINT_TYPE(true, "schema-change-after-point"),

    /** Triggered by the user. */
    SAVEPOINT_TYPE(false, "savepoint"),

    /** Automatically triggered by the Task. */
    COMPLETED_POINT_TYPE(true, "completed-point");

    private final boolean auto;
    private final String name;

    public static CheckpointType fromName(String name) {
        for (CheckpointType type : CheckpointType.values()) {
            if (type.name.equals(name)) {
                return type;
            }
        }
        throw new IllegalArgumentException("Unknown checkpoint type: " + name);
    }

    CheckpointType(boolean auto, String name) {
        this.auto = auto;
        this.name = name;
    }

    public boolean isAuto() {
        return auto;
    }

    public String getName() {
        return name;
    }

    public boolean isFinalCheckpoint() {
        return this == COMPLETED_POINT_TYPE || this == SAVEPOINT_TYPE;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Use one of the exact enum names accepted by CheckpointType (check the enum constants in CheckpointType.java) with correct case.
Omit the option to use the default checkpoint type for normal streaming/batch jobs.
If migrating from an older version, update persisted job/state files to the current enum names.

Example fix

// before
CheckpointType.fromName("SavePoint");
// after
CheckpointType.fromName("savepoint");

Defensive patterns

Strategy: validation

Validate before calling

Set<String> valid = Arrays.stream(CheckpointType.values()).map(CheckpointType::name).collect(Collectors.toSet());
if (!valid.contains(inputName)) throw new IllegalArgumentException("checkpoint type must be one of " + valid + ", got: " + inputName);

Try / catch

try { CheckpointType.fromName(name); } catch (IllegalArgumentException e) { log.error("bad checkpoint type '{}', use exact enum name", name, e); throw e; }

Prevention

Use CheckpointType enum constants directly in code instead of raw strings.
Copy config values from docs, matching case exactly.
When migrating, regenerate job/savepoint metadata instead of hand-editing names.

When it happens

Trigger: Calling CheckpointType.fromName(name) with a string that is not an exact match of any enum constant's name — typically an unknown value read from job configuration or deserialized state.

Common situations: Typo or wrong case in job config (e.g. 'SavePoint' vs 'savepoint'); restoring a job with a checkpoint type name produced by an incompatible older/newer SeaTunnel version; hand-edited job JSON.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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