apache/beam · error · IllegalArgumentException

Received null value for non-nullable field "{}"

Error message

Received null value for non-nullable field "{}"

What it means

YamlUtils.toBeamValue converts a single YAML value to its Beam schema representation. If the YAML value is null but the field's schema type is non-nullable, this IllegalArgumentException names the offending field, since a null cannot satisfy a required field.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/YamlUtils.java:100

    Preconditions.checkArgument(
        yamlMap instanceof Map,
        "Expected a YAML mapping but got type '%s' instead.",
        Preconditions.checkNotNull(yamlMap).getClass());

    return toBeamRow(
        (Map<String, Object>) Preconditions.checkNotNull(yamlMap), schema, convertNamesToCamelCase);
  }

  private static @Nullable Object toBeamValue(
      Field field, @Nullable Object yamlValue, boolean convertNamesToCamelCase) {
    FieldType fieldType = field.getType();

    if (yamlValue == null) {
      if (fieldType.getNullable()) {
        return null;
      } else {
        throw new IllegalArgumentException(
            "Received null value for non-nullable field \"" + field.getName() + "\"");
      }
    }

    if (yamlValue instanceof String
        || yamlValue instanceof Number
        || yamlValue instanceof Boolean) {
      String yamlStringValue = yamlValue.toString();
      if (YAML_VALUE_PARSERS.containsKey(fieldType.getTypeName())) {
        return YAML_VALUE_PARSERS.get(fieldType.getTypeName()).apply(yamlStringValue);
      }
    }

    if (yamlValue instanceof byte[] && fieldType.getTypeName() == Schema.TypeName.BYTES) {
      return yamlValue;
    }

    if (yamlValue instanceof List) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Supply a value for the field in the YAML document.
2. Mark the field nullable in the schema if nulls are valid in the data.
3. Pre-validate the YAML document and fill/remove nulls for required keys before conversion.
4. Use defaults when deserializing so required fields never surface as null.

Example fix

// before (YAML)
name:
age: 5
// after
name: anonymous
age: 5

for (Map.Entry<String, Object> e : yamlMap.entrySet()) {
  Schema.Field f = schema.getField(e.getKey());
  if (e.getValue() == null && !f.getType().getNullable())
    throw new IllegalArgumentException("null for non-nullable field: " + f.getName());
}

boolean nullAllowed(Schema schema, String fieldName) {
  return schema.getField(fieldName).getType().getNullable();
}

try {
  return YamlUtils.toBeamRow(yamlString, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("non-nullable field")) {
    logger.warning("Null in required field: " + e.getMessage());
    return null; // or route to dead-letter
  }
  throw e;
}

When it happens

Trigger: A YAML document contains a key with an explicit null value (or an omitted key mapping to null) while the corresponding schema field has getNullable() == false; recursing via toBeamRow into nested objects triggers the same check per field.

Common situations: YAML like `name:` (explicit null), missing nested keys defaulting to null, or schema marked required incorrectly while data legitimately contains nulls.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Null value found for field that doesn't support nulls.
• FieldTypeValue has no value but the field cannot be null.
• Most (%s) and least (%s) significant bits value shouldn't be
• Received an empty YAML string, but output schema contains re
• Converting YAML type '%s' to '%s' is not supported

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