apache/seatunnel · error · IllegalArgumentException

Unknown restore mode code:

Error message

Unknown restore mode code: 

What it means

RestoreMode.fromCode maps an integer code to a RestoreMode enum value (NONE, DEFAULT, WAIT, etc.). If the code does not match any enum member, an IllegalArgumentException with 'Unknown restore mode code' is thrown. This protects against deserializing an unrecognized restore-mode code, often from newer/older binary versions.

Solutions

1. Use only codes present in RestoreMode.values() (check the enum source)
2. Ensure client and server SeaTunnel versions match so enum codes align
3. Replace raw int codes with the enum constant in caller code (RestoreMode.DEFAULT etc.)
4. Add a migration step to remap unknown codes from old state before deserialization

Example fix

// before
RestoreMode mode = RestoreMode.fromCode(99); // throws
// after
RestoreMode mode = Arrays.stream(RestoreMode.values())
        .filter(m -> m.getCode() == 99)
        .findFirst()
        .orElse(RestoreMode.DEFAULT);

boolean known = Arrays.stream(RestoreMode.values()).anyMatch(m -> m.getCode() == code);

static Optional<RestoreMode> safeFromCode(int code) {
    return Arrays.stream(RestoreMode.values())
            .filter(m -> m.getCode() == code)
            .findFirst();
}

try {
    mode = RestoreMode.fromCode(code);
} catch (IllegalArgumentException e) {
    log.warn("Unknown restore mode code {}, falling back to DEFAULT", code);
    mode = RestoreMode.DEFAULT;
}

When it happens

Trigger: Calling RestoreMode.fromCode(code) with a code that is not one of the defined enum values; typically from deserialized job/checkpoint state, REST API input, or cross-version serialization where the enum set differs.

Common situations: Upgrading or downgrading SeaTunnel so a newer code is read by an older binary; a REST client posts a bogus restoreMode integer; state serialized with a custom code value.

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

• CONFIG_VALIDATION_FAILED
• failed to serialize event as JSON
• failed to serialize event as JSON
• SERIALIZATION_ERROR
• UNSUPPORTED_DATA_TYPE

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-core/src/main/java/org/apache/seatunnel/engine/core/job/RestoreMode.java:59

    }

    /** Returns the stable persisted and wire-level code for this restore mode. */
    public int getCode() {
        return code;
    }

    /**
     * Resolves a stable persisted or wire-level code to its restore mode.
     *
     * @throws IllegalArgumentException if the code is unknown
     */
    public static RestoreMode fromCode(int code) {
        for (RestoreMode restoreMode : values()) {
            if (restoreMode.code == code) {
                return restoreMode;
            }
        }
        throw new IllegalArgumentException("Unknown restore mode code: " + code);
    }

    /** Returns whether this mode requires checkpoint or savepoint state to be restored. */
    public boolean isRestore() {
        return this != NONE;
    }
}

View on GitHub (pinned to cf67b549a7)