apache/beam · error · UnsupportedRowJsonException

Value "{value}" is out of range for the type of the field de

Error message

Value "{value}" is out of range for the type of the field defined in the row schema.

What it means

Thrown by ValidatingValueExtractor.extractValue when a JSON value passes type checks but fails the row-schema validator's predicate (e.g. an integer outside the field's declared range). The library refuses to map values that cannot be represented in the Beam Row schema. The exception message includes the offending value's text representation.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/RowJsonValueExtractors.java:268

        .setValidator(JsonNode::isTextual)
        .build();
  }

  @AutoValue
  public abstract static class ValidatingValueExtractor<W> implements ValueExtractor<W> {

    abstract Predicate<JsonNode> validator();

    abstract Function<JsonNode, W> extractor();

    static <T> Builder<T> builder() {
      return new AutoValue_RowJsonValueExtractors_ValidatingValueExtractor.Builder<>();
    }

    @Override
    public W extractValue(JsonNode value) {
      if (!validator().test(value)) {
        throw new UnsupportedRowJsonException(
            "Value \""
                + value.asText()
                + "\" "
                + "is out of range for the type of the field defined in the row schema.");
      }

      return extractor().apply(value);
    }

    @AutoValue.Builder
    abstract static class Builder<W> {
      abstract Builder<W> setValidator(Predicate<JsonNode> validator);

      abstract Builder<W> setExtractor(Function<JsonNode, W> extractor);

      abstract ValidatingValueExtractor<W> build();
    }
  }

View on GitHub (pinned to 12126d8942)

Solutions

Check the value at the offending record against the row schema field type and widen the schema field type (e.g. INT32 -> INT64) if the data legitimately exceeds the range.
Pre-filter or sanitize the JSON data before conversion so out-of-range values are rejected, defaulted, or clamped upstream.
Catch UnsupportedRowJsonException and route the bad record to a dead-letter output for inspection.

Example fix

// before
Row row = rowJsonConverter.convert(jsonNode); // throws for huge numbers
// after
if (jsonNode.get("count").canConvertToLong()) {
  Row row = rowJsonConverter.convert(jsonNode);
} else {
  deadLetterOutput.output(jsonNode.toString());
}

Defensive patterns

Strategy: validation

Validate before calling

boolean inRange = jsonNode.canConvertToInt() /* or canConvertToLong() */;
if (!inRange) { deadLetter(jsonNode); return; }

Try / catch

try { row = extractor.extractValue(node); } catch (UnsupportedRowJsonException e) { deadLetterOutput.output(node.toString()); }

Prevention

Define row schema field types wide enough for the source JSON data.
Validate sample data against the schema before full pipeline runs.
Route schema-violating records to a dead-letter sink instead of failing the pipeline.

When it happens

Trigger: Calling extractValue on a JsonNode whose value is outside the allowed range for the schema field type, e.g. a JSON number larger than a Long field can hold, or a value failing the validator predicate configured for the extractor.

Common situations: Converting JSON documents into Beam Rows where a field contains a number beyond the declared schema type (e.g. a huge integer against an INT64 field), or string/numeric values that violate schema constraints during data ingestion from JSON sources.

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

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