apache/seatunnel · error · IllegalArgumentException

Unsupported error handler mode

Error message

Unsupported error handler mode: %s

What it means

ErrorHandlerMode.fromString converts a configured string into the ErrorHandlerMode enum, accepting only LOG, ROUTE, and DISABLE. Any other value throws IllegalArgumentException 'Unsupported error handler mode'. This validates the top-level error-handler strategy selection.

Solutions

1. Set the mode to one of the supported values: LOG, ROUTE, or DISABLE.
2. Use the uppercase form exactly as the enum constant is spelled.
3. If a custom strategy is needed, implement it via the ROUTE target rather than inventing a mode name.

Example fix

// before
error-handler.mode = "IGNORE"
// after
error-handler.mode = "LOG"

Set<String> allowed = Set.of("LOG", "ROUTE", "DISABLE");
String mode = cfg.get("error-handler.mode");
if (mode != null && !allowed.contains(mode)) {
    throw new IllegalArgumentException("Unsupported error handler mode: " + mode);
}

boolean isValidErrorHandlerMode(String s) {
    return "LOG".equals(s) || "ROUTE".equals(s) || "DISABLE".equals(s);
}

try {
    ErrorHandlerMode m = ErrorHandlerMode.fromString(value);
} catch (IllegalArgumentException e) {
    log.error("Bad mode '{}'; use LOG, ROUTE, or DISABLE", value);
}

When it happens

Trigger: Setting the error-handler mode option to an unrecognized string such as 'IGNORE', 'log' lowercase (if exact match is required per source), 'retry', or a typo like 'DISBLE'.

Common situations: Users copy modes from other frameworks (e.g. Flink 'SKIP', Kafka 'DLQ') or typo the uppercase constant names.

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

• Unsupported error handler queue_overflow_policy
• Cannot resolve insert strategy
• COMMON_ILLEGAL_ARGUMENT
• must in [SHARED, ISOLATED]
• connector-jar-storage-mode must in [SHARED, ISOLATED]

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/error/ErrorHandlerMode.java:37

public enum ErrorHandlerMode {
    DISABLE,
    LOG,
    ROUTE;

    public static ErrorHandlerMode fromString(String value) {
        if (value == null) {
            return DISABLE;
        }
        switch (value.trim().toUpperCase()) {
            case "LOG":
                return LOG;
            case "ROUTE":
                return ROUTE;
            case "DISABLE":
                return DISABLE;
            default:
                throw new IllegalArgumentException("Unsupported error handler mode: " + value);
        }
    }
}

View on GitHub (pinned to cf67b549a7)