apache/beam · error · IllegalArgumentException

" + typeName + " overflow: " + v.toPlainString()

Error message

" + typeName + " overflow: " + v.toPlainString()

What it means

serializeBigDecimal enforces the magnitude bounds of the target BigQuery type (NUMERIC: ~1e38 precision, or BIGNUMERIC). A BigDecimal outside [minValue, maxValue] throws IllegalArgumentException, since BigQuery NUMERIC cannot represent it.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BeamRowToStorageApiProto.java:447

    Object value = toProtoValue(valueFieldDescriptor, valueFieldType, entryValue.getValue());
    if (value != null) {
      builder.setField(valueFieldDescriptor, value);
    }
    return builder.build();
  }

  static ByteString serializeBigDecimalToNumeric(BigDecimal o) {
    return serializeBigDecimal(o, NUMERIC_SCALE, MAX_NUMERIC_VALUE, MIN_NUMERIC_VALUE, "Numeric");
  }

  private static ByteString serializeBigDecimal(
      BigDecimal v, int scale, BigDecimal maxValue, BigDecimal minValue, String typeName) {
    if (v.scale() > scale) {
      throw new IllegalArgumentException(
          typeName + " scale cannot exceed " + scale + ": " + v.toPlainString());
    }
    if (v.compareTo(maxValue) > 0 || v.compareTo(minValue) < 0) {
      throw new IllegalArgumentException(typeName + " overflow: " + v.toPlainString());
    }

    byte[] bytes = v.setScale(scale).unscaledValue().toByteArray();
    // NUMERIC/BIGNUMERIC values are serialized as scaled integers in two's complement form in
    // little endian
    // order. BigInteger requires the same encoding but in big endian order, therefore we must
    // reverse the bytes that come from the proto.
    Bytes.reverse(bytes);
    return ByteString.copyFrom(bytes);
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Clamp or validate values upstream before the BigQuery sink
2. Change the BigQuery column to BIGNUMERIC or FLOAT64 and use the matching serializer
3. Pre-check with compareTo against MAX_NUMERIC_VALUE/MIN_NUMERIC_VALUE in pipeline code

Example fix

// before
row.getDecimal("amount") // 1e40, overflows NUMERIC
// after
if (amount.compareTo(MAX_NUMERIC_VALUE) > 0) { amount = amount.setScale(0, RoundingMode.DOWN); /* or reroute */ }

BigDecimal max = new BigDecimal("99999999999999999999999999999.999999999");
if (value.compareTo(max) > 0 || value.compareTo(max.negate()) < 0) throw new IllegalArgumentException("NUMERIC overflow: " + value);

When it happens

Trigger: serializeBigDecimalToNumeric (or the BIGNUMERIC variant) receives a BigDecimal whose absolute value exceeds the type's max (NUMERIC max ≈ 99999999999999999999999999999.999999999) or is below its min.

Common situations: Unbounded aggregates (sums of huge values), misclassified columns (NUMERIC used for data needing BIGNUMERIC/DOUBLE), or upstream data with extremely large amounts.

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

• " + typeName + " scale cannot exceed " + scale + ": " + v.to
• Unsupported format for BigQuery table path: '{linkedResource
• Reserved field name <field.name()> in user schema.
• Unsupported type <elementType.getType()>
• Received null value for non-nullable field " + fieldDescript

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/c7d23fea8861301b. Report an issue: GitHub.