apache/seatunnel · error · IllegalArgumentException

Unsupported error handler queue_overflow_policy

Error message

Unsupported error handler queue_overflow_policy: %s

What it means

QueueOverflowPolicy.fromString converts the queue_overflow_policy option into its enum, accepting only DROP, BLOCK, and FAIL. Any other value throws IllegalArgumentException 'Unsupported error handler queue_overflow_policy'. This controls what happens when the error-handling queue is full.

Solutions

1. Use one of the supported values exactly: DROP, BLOCK, or FAIL.
2. Match uppercase spelling of the enum constant.
3. Choose FAIL if you want the task to fail on queue overflow rather than drop or block.

Example fix

// before
error-handler.queue_overflow_policy = "SKIP"
// after
error-handler.queue_overflow_policy = "BLOCK"

Set<String> allowed = Set.of("DROP", "BLOCK", "FAIL");
String policy = cfg.get("queue_overflow_policy");
if (policy != null && !allowed.contains(policy)) {
    throw new IllegalArgumentException("Unsupported queue_overflow_policy: " + policy);
}

boolean isValidQueueOverflowPolicy(String s) {
    return "DROP".equals(s) || "BLOCK".equals(s) || "FAIL".equals(s);
}

try {
    QueueOverflowPolicy p = QueueOverflowPolicy.fromString(value);
} catch (IllegalArgumentException e) {
    log.error("Bad policy '{}'; use DROP, BLOCK, or FAIL", value);
}

When it happens

Trigger: Configuring 'queue_overflow_policy = discard', 'SKIP', or any value other than DROP, BLOCK, FAIL in the error-handler block.

Common situations: Users borrow policy names from other systems (e.g. 'backpressure', 'latest', 'oldest' from Kafka consumer offset reset) or misspell the constant.

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 mode
• 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/4d3982ed638eb21a. Report an issue: GitHub.

Appendix: source

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

public enum QueueOverflowPolicy {
    FAIL,
    DROP,
    BLOCK;

    public static QueueOverflowPolicy fromString(String value) {
        if (value == null) {
            return FAIL;
        }
        switch (value.trim().toUpperCase()) {
            case "DROP":
                return DROP;
            case "BLOCK":
                return BLOCK;
            case "FAIL":
                return FAIL;
            default:
                throw new IllegalArgumentException(
                        "Unsupported error handler queue_overflow_policy: " + value);
        }
    }
}

View on GitHub (pinned to cf67b549a7)