apache/beam · error · UnsupportedRowJsonException

Non-nullable field '{name}' has value null in the JSON objec

Error message

Non-nullable field '{name}' has value null in the JSON object.

What it means

RowJson's deserializer rejects JSON null values for schema fields declared non-nullable. Beam Rows enforce nullability per field, so a JSON null mapped to a non-nullable field violates the schema and throws UnsupportedRowJsonException.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/RowJson.java:306

        }

        if (fieldValue.isJsonNull()) {
          switch (this.nullBehavior) {
            case ACCEPT_MISSING_OR_NULL:
            case REQUIRE_NULL:
              return null;
            case REQUIRE_MISSING:
              throw new UnsupportedRowJsonException(
                  "Field '" + fieldValue.name() + "' has a null value in the JSON object.");
          }
        }
      } else {
        // field is not nullable
        if (!fieldValue.isJsonValuePresent()) {
          throw new UnsupportedRowJsonException(
              "Non-nullable field '" + fieldValue.name() + "' is not present in the JSON object.");
        } else if (fieldValue.isJsonNull()) {
          throw new UnsupportedRowJsonException(
              "Non-nullable field '" + fieldValue.name() + "' has value null in the JSON object.");
        }
      }

      if (fieldValue.isRowType()) {
        return jsonObjectToRow(fieldValue);
      }

      if (fieldValue.isArrayType()) {
        return jsonArrayToList(fieldValue);
      }

      if (fieldValue.isMapType()) {
        return jsonObjectToMap(fieldValue);
      }

      if (fieldValue.typeName().isLogicalType()) {
        String identifier = fieldValue.type().getLogicalType().getIdentifier();

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure producers emit real values instead of null for non-nullable fields
2. Make the field nullable in the schema if nulls are legitimate
3. Filter or default out null values in a pre-processing step before jsonToRow
4. Catch UnsupportedRowJsonException and route the record to an error path

Example fix

// before
{"id": null}
// after: make schema field nullable, or supply a value
{"id": "abc"}

for (Schema.Field f : schema.getFields()) {
  if (!f.getType().getNullable() && json.has(f.getName()) && json.get(f.getName()).isNull()) {
    throw new IllegalArgumentException("Null value for non-nullable field: " + f.getName());
  }
}

try { Row r = RowJsonUtils.jsonToRow(mapper, json); } catch (RowJson.UnsupportedRowJsonException e) { /* log + dead-letter */ }

When it happens

Trigger: jsonToRow / objectMapper.readValue with a JSON object that explicitly contains "field": null for a field marked non-nullable in the Row schema.

Common situations: Nullable-JSON APIs returning nulls for missing data; schema changed a field from nullable to non-nullable after producers were written; generic JSON-to-Row pipelines ingesting arbitrary payloads.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Non-nullable field '{name}' is not present in the JSON objec
• Value "{value}" is out of range for the type of the field de
• %s requires an input Schema. Note that only Row or user clas
• Unable to generate coder for schema {schema}
• Expecting exactly one field, found

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