What causes "Null field values are not supported" in apache/beam?

Ensure all argument values are non-null, providing defaults where needed

apache/beam · error · RuntimeException

Null field values are not supported

Error message

Null field values are not supported

What it means

generateSchemaDirectly builds a Beam Schema from a row of field values so kwargs can be serialized for Python expansion. Since the field type of each value must be inferred from the value itself, a null field value makes type inference impossible and the library throws RuntimeException. All field values used to generate the schema must be non-null.

Solutions

Ensure all argument values are non-null, providing defaults where needed
Register an explicit withTypeHint(Class, Schema.FieldType) for the affected type and pass a non-null value
Filter out null entries before building the kwargs

Example fix

// before
transform.withArgs(values); // values may contain nulls
// after
transform.withArgs(Arrays.stream(values).map(v -> v != null ? v : DEFAULT).toArray());

Defensive patterns

Strategy: validation

Validate before calling

for (Object v : fieldValues) {
  if (v == null) throw new IllegalArgumentException("schema fields must be non-null");
}
transform.withKwargs(...);

Type guard

boolean hasNoNulls(Object[] vals) {
  return java.util.Arrays.stream(vals).allMatch(java.util.Objects::nonNull);
}

Try / catch

try {
  transform.withArgs(fieldValues);
} catch (RuntimeException e) {
  if (e.getMessage().contains("Null field values")) {
    // add withTypeHint for the affected type or default the value
  }
}

Prevention

Provide explicit withTypeHint for types that may arrive null-wrapped or custom
Replace null fields with typed defaults before building kwargs
Assert argument arrays are null-free in tests

When it happens

Trigger: Passing null in the varargs of withKwargs/args when no explicit type hints cover the value; generateSchemaFromFieldValues calls generateSchemaDirectly with an array containing nulls.

Common situations: Null optional parameters forwarded into kwargs; collections containing null elements passed as a single argument; uninitialized fields of a config bean used as kwargs.

Related errors

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

Appendix: source

Thrown at sdks/java/extensions/python/src/main/java/org/apache/beam/sdk/extensions/python/PythonExternalTransform.java:380

      }
    }
    return converted;
  }

  @VisibleForTesting
  Row buildOrGetArgsRow() {
    Schema schema = generateSchemaFromFieldValues(argsArray, null);
    Object[] convertedValues = convertComplexTypesToRows(argsArray);
    return Row.withSchema(schema).addValues(convertedValues).build();
  }

  private Schema generateSchemaDirectly(
      @Nullable Object @NonNull [] fieldValues, @NonNull String @Nullable [] fieldNames) {
    Schema.Builder builder = Schema.builder();
    int counter = 0;
    for (Object field : fieldValues) {
      if (field == null) {
        throw new RuntimeException("Null field values are not supported");
      }
      String fieldName = (fieldNames != null) ? fieldNames[counter] : "field" + counter;
      if (field instanceof Row) {
        // Rows are used as is but other types are converted to proper field types.
        builder.addRowField(fieldName, ((Row) field).getSchema());
      } else if (typeHints.containsKey(field.getClass())) {
        builder.addField(fieldName, typeHints.get(field.getClass()));
      } else {
        builder.addField(
            fieldName,
            StaticSchemaInference.fieldFromType(
                TypeDescriptor.of(field.getClass()),
                JavaFieldSchema.JavaFieldTypeSupplier.INSTANCE));
      }

      counter++;
    }

View on GitHub (pinned to 12126d8942)