apache/seatunnel · error · IllegalArgumentException

error handler must be between 0 and , but was

Error message

error handler %s must be between 0 and %s, but was %s

What it means

getNonNegativeInt validates that an integer error-handler option fits in the non-negative int range [0, Integer.MAX_VALUE]. Values below 0 or above 2^31-1 throw IllegalArgumentException with the key, upper bound, and offending value. It applies to options like maxErrorRatioMinRecords, queueCapacity, and originalDataMaxLength.

Solutions

1. Set the option to a non-negative value that fits in a 32-bit int (<= 2147483647).
2. If 'unlimited' was intended, check the option's documented default/disabled semantics instead of using -1.
3. If a larger limit is genuinely needed, reduce it or ask for a long-typed option; do not exceed Integer.MAX_VALUE.

Example fix

// before
error-handler.queue-capacity = -1
// after
error-handler.queue-capacity = 1024

long v = getLong(stage, global, key, def);
if (v < 0 || v > Integer.MAX_VALUE) {
    throw new IllegalArgumentException(key + " must be in [0, 2147483647], got: " + v);
}

boolean isValidNonNegativeInt(long v) {
    return v >= 0 && v <= Integer.MAX_VALUE;
}

try {
    int cap = ErrorHandlerConfigUtil.queueCapacity(...);
} catch (IllegalArgumentException e) {
    log.error("Out-of-range error-handler int: {}", e.getMessage());
}

When it happens

Trigger: Configuring e.g. 'error-handler.queue-capacity = -1' or 'originalDataMaxLength = 99999999999' (overflowing int) so getLong returns a value outside the allowed range.

Common situations: Users set -1 expecting 'unlimited' semantics (common in other systems like Kafka clients), or set byte/record limits in long magnitudes exceeding int range.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid error handler boolean value for
• Unsupported error handler mode
• Unsupported error handler queue_overflow_policy
• accessId and accesskey must be provided when sts_token is…
• Agent config is not a readable file

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

Appendix: source

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

        if (value != null) {
            String booleanValue = value.toString().trim();
            if ("true".equalsIgnoreCase(booleanValue)) {
                return true;
            }
            if ("false".equalsIgnoreCase(booleanValue)) {
                return false;
            }
            throw new IllegalArgumentException(
                    "Invalid error handler boolean value for '" + key + "': " + value);
        }
        return defaultValue;
    }

    private static int getNonNegativeInt(
            Map<String, Object> stage, Map<String, Object> global, String key, int defaultValue) {
        long value = getLong(stage, global, key, defaultValue);
        if (value < 0 || value > Integer.MAX_VALUE) {
            throw new IllegalArgumentException(
                    "error handler "
                            + key
                            + " must be between 0 and "
                            + Integer.MAX_VALUE
                            + ", but was "
                            + value);
        }
        return (int) value;
    }
}

View on GitHub (pinned to cf67b549a7)