apache/seatunnel · error · IllegalArgumentException

Integer value is out of range

Error message

Integer value is out of range

What it means

DocumentDBItemDeserializer.checkedInteger converts a BSON numeric value to int for SeaTunnel INT columns and throws IllegalArgumentException if the numeric value falls outside [minimum, maximum] (e.g. Integer.MIN/MAX_VALUE). This prevents silent truncation when converting long/double/decimal BSON values to Java int.

Source

Thrown at seatunnel-connectors-v2/connector-amazondocumentdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/amazondocumentdb/serialize/DocumentDBItemDeserializer.java:138

            throw e;
        } catch (RuntimeException e) {
            SeaTunnelRuntimeException error = conversionError(field, type);
            error.initCause(e);
            throw error;
        }
    }

    private static boolean isNull(BsonValue value) {
        return value == null
                || value.isNull()
                || value.getBsonType() == BsonType.UNDEFINED
                || (value.isDecimal128() && value.asDecimal128().getValue().isNaN());
    }

    private static int checkedInteger(BsonValue value, int minimum, int maximum) {
        long number = value.asNumber().longValue();
        if (number < minimum || number > maximum) {
            throw new IllegalArgumentException("Integer value is out of range");
        }
        return (int) number;
    }

    private static long checkedLong(BsonValue value) {
        if (value.isInt32() || value.isInt64()) {
            return value.asNumber().longValue();
        }
        if (value.isDouble()) {
            double number = value.asNumber().doubleValue();
            if (number < Long.MIN_VALUE || number > Long.MAX_VALUE) {
                throw new IllegalArgumentException("Long value is out of range");
            }
            return value.asNumber().longValue();
        }
        throw new IllegalArgumentException("Value is not a supported long");
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Widen the SeaTunnel column type from int to bigint in the schema so large values fit.
2. Fix the source data or filter out rows with out-of-range values via the match query.
3. If conversion is expected to be lossy, pre-clamp values in the source or a transform stage.

Example fix

// before
{"name": "count", "type": "int"}   // source value 3,000,000,000
// after
{"name": "count", "type": "bigint"}

long v = bsonValue.asNumber().longValue();
if (v < Integer.MIN_VALUE || v > Integer.MAX_VALUE) {
    throw new IllegalArgumentException("value does not fit int column: " + v);
}

try {
    // deserialize row
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("out of range")) {
        log.error("INT column overflow from DocumentDB value", e);
    }
}

When it happens

Trigger: A BSON field mapped to SeaTunnel INT contains a value like 3_000_000_000 (int64 or double) exceeding Integer.MAX_VALUE, or below Integer.MIN_VALUE.

Common situations: Source collection holds large counters/IDs stored as int64 but the SeaTunnel schema declares the column as int; a decimal value rounds to a number outside 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

• Long value is out of range
• COMMON-17
• Unsupported convert %s to %s
• Unsupported convert ${value.getClass()} to LocalTime, typeDe
• Unsupported convert ${value.getClass()} to LocalTime

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