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

Replace null kwargs with an explicit non-null sentinel or default value

apache/beam · error · RuntimeException

Null values are not supported

Error message

Null values are not supported

What it means

convertComplexTypesToRows converts Java kwargs values into Beam Rows for the Python expansion service. Null entries cannot be represented in this conversion, so the library throws RuntimeException when any element of the values array is null. Every kwarg passed via withKwarg/kwargs must be non-null and convertible.

Solutions

Replace null kwargs with an explicit non-null sentinel or default value
Skip the withKwarg call entirely when the value is null so the Python default is used
Wrap nullable values (e.g. Optional.ofNullable(...).orElse(default)) before passing

Example fix

// before
transform.withKwarg("limit", maybeLimit); // NPE when null
// after
if (maybeLimit != null) {
  transform.withKwarg("limit", maybeLimit);
}

Defensive patterns

Strategy: validation

Validate before calling

if (value == null) {
  throw new IllegalArgumentException("kwarg '" + name + "' must be non-null");
}
transform.withKwarg(name, value);

Type guard

boolean isUsableKwarg(Object v) { return v != null; }

Try / catch

try {
  transform.withKwarg(name, value);
} catch (RuntimeException e) {
  if (e.getMessage().contains("Null values are not supported")) {
    // supply a default or drop the kwarg
  }
}

Prevention

Never pass null kwarg/arg values; skip the withKwarg call instead
Use Optional or explicit defaults when converting config to kwargs
Sanitize maps of kwargs for null entries before applying

When it happens

Trigger: Passing a null value as an argument via withKwarg/withArgs (e.g. withKwarg("name", null)) or building kwargs from a map/nullable variables that contain nulls; convertComplexTypesToRows is invoked from buildOrGetKwargsRow/convertedValues during payload generation.

Common situations: Optional Java parameters left null and forwarded straight into kwargs; configuration objects with absent fields passed as-is; ternary expressions like config.get("x") returning null.

Related errors

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

Appendix: source

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

      SCHEMA_REGISTRY.registerSchemaProvider(value.getClass(), new JavaFieldSchema());
      try {
        toRowFunc =
            (SerializableFunction<Object, Row>) SCHEMA_REGISTRY.getToRowFunction(value.getClass());
      } catch (NoSuchSchemaException e1) {
        throw new RuntimeException(e1);
      }
    }
    return toRowFunc.apply(value);
  }

  private Object[] convertComplexTypesToRows(@Nullable Object @NonNull [] values) {
    Object[] converted = new Object[values.length];
    for (int i = 0; i < values.length; i++) {
      Object value = values[i];
      if (value != null) {
        converted[i] = isCustomType(value.getClass()) ? convertCustomValue(value) : value;
      } else {
        throw new RuntimeException("Null values are not supported");
      }
    }
    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) {

View on GitHub (pinned to 12126d8942)