apache/seatunnel · error · IllegalArgumentException

Decimal precision %d exceeds configured precision %d

Error message

Decimal precision %d exceeds configured precision %d

What it means

DocumentDBItemDeserializer.convertDecimal converts a BSON Decimal128 into a BigDecimal scaled to the configured SeaTunnel DecimalType. After scaling with HALF_UP rounding, if the resulting precision (total significant digits) still exceeds the configured precision, it throws this IllegalArgumentException. This guards that data written downstream matches the declared schema precision.

Source

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

            }
            return value.asNumber().longValue();
        }
        throw new IllegalArgumentException("Value is not a supported long");
    }

    /**
     * Applies the configured scale and rejects precision overflow instead of silently emitting
     * {@code null}, which would make malformed source data indistinguishable from BSON null.
     */
    private static BigDecimal convertDecimal(DecimalType type, BsonValue value) {
        Decimal128 decimal128 = value.asDecimal128().decimal128Value();
        if (!decimal128.isFinite()) {
            throw new IllegalArgumentException("Infinite Decimal128 values are not supported");
        }
        BigDecimal decimal =
                decimal128.bigDecimalValue().setScale(type.getScale(), RoundingMode.HALF_UP);
        if (decimal.precision() > type.getPrecision()) {
            throw new IllegalArgumentException(
                    String.format(
                            "Decimal precision %d exceeds configured precision %d",
                            decimal.precision(), type.getPrecision()));
        }
        return decimal;
    }

    private static String convertString(BsonValue value) {
        if (value.isString()) {
            return value.asString().getValue();
        }
        if (value.isObjectId()) {
            return value.asObjectId().getValue().toHexString();
        }
        if (value.isDocument()) {
            return value.asDocument().toJson(RELAXED_JSON_SETTINGS);
        }
        return value.toString();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Increase the precision of the DECIMAL type in the SeaTunnel schema so it covers the integer digits plus scale (precision >= integerDigits + scale).
2. Pre-clean or truncate the Decimal128 values in DocumentDB (e.g. aggregate pipeline with $trunc or $round) so they fit the configured precision.
3. Map the field to DOUBLE instead of DECIMAL if exact precision is not required.
4. Wrap the read in error handling that routes offending rows to a dead-letter path instead of failing the job.

Example fix

// before: schema too narrow for the data
 DECIMAL(10,2)
// after: widen precision to fit values up to 12 integer digits + 2 decimals
 DECIMAL(14,2)

BigDecimal scaled = decimal128.bigDecimalValue().setScale(targetScale, RoundingMode.HALF_UP);
if (scaled.precision() > targetPrecision) {
    throw new IllegalArgumentException("Value " + scaled + " exceeds DECIMAL(" + targetPrecision + "," + targetScale + ")");
}

boolean fitsDecimal(BigDecimal v, int precision) { return v.precision() <= precision; }

try { row = deserializer.convert(field, decimalType, bsonValue); } catch (IllegalArgumentException e) { log.warn("Decimal overflow for field {}: {}", field, e.getMessage()); routeToDeadLetter(field, bsonValue); }

When it happens

Trigger: Reading a DocumentDB document whose Decimal128 field has more significant digits than the precision declared for the corresponding DECIMAL column in the SeaTunnel schema (e.g. a Decimal128 with 20 digits against DECIMAL(10,2)), even after rounding the scale down.

Common situations: Source collection holds high-precision monetary or scientific values while the SeaTunnel schema was declared with a small DECIMAL(p,s); schema inferred from a sample that contained small values but production data has larger magnitudes (integer-digit overflow, which rounding cannot fix).

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

• Decimal type should assign precision and scale information
• Unsupported convert ${value.getClass()} to BigDecimal, typeD
• Unsupported convert ${value.getClass()} to BigDecimal
• columnDefine size not match
• typeDefine size not match

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