apache/beam · error · IllegalArgumentException

Can't convert 'null' to FieldType

Error message

Can't convert 'null' to FieldType

What it means

When converting an AVRO schema to a Beam Schema, a top-level Avro Schema.Type.NULL is encountered. Beam's FieldType model has no representation for a bare 'null' type (null is only modeled as nullability on another type), so the library throws IllegalArgumentException instead of guessing a representation.

Source

Thrown at sdks/java/extensions/avro/src/main/java/org/apache/beam/sdk/extensions/avro/schemas/utils/AvroUtils.java:1125

        case DOUBLE:
          fieldType = FieldType.DOUBLE;
          break;

        case BOOLEAN:
          fieldType = FieldType.BOOLEAN;
          break;

        case UNION:
          fieldType =
              FieldType.logicalType(
                  OneOfType.create(
                      avroSchema.getTypes().stream()
                          .map(x -> Field.of(x.getName(), toFieldType(new TypeWithNullability(x))))
                          .collect(Collectors.toList())));
          break;
        case NULL:
          throw new IllegalArgumentException("Can't convert 'null' to FieldType");

        default:
          throw new AssertionError("Unexpected AVRO Schema.Type: " + avroSchema.getType());
      }
    }
    fieldType = fieldType.withNullable(type.nullable);
    return fieldType;
  }

  private static org.apache.avro.Schema getFieldSchema(
      FieldType fieldType, String fieldName, String namespace) {
    org.apache.avro.Schema baseType;
    switch (fieldType.getTypeName()) {
      case BYTE:
      case INT16:
      case INT32:
        baseType = org.apache.avro.Schema.create(org.apache.avro.Schema.Type.INT);
        break;

View on GitHub (pinned to 12126d8942)

Solutions

1. Rewrite the Avro schema so 'null' only appears in unions with a concrete type, e.g. ['null','string'] instead of ['null'] or NULL.
2. If the field is truly optional, model it with a concrete union branch; Beam maps that to a nullable FieldType automatically.
3. Strip or default null-only fields from the schema before conversion.
4. Catch IllegalArgumentException around toBeamSchema and fail fast with a clear schema-validation message.

Example fix

// before
{"name":"opt","type":"null"}
// after
{"name":"opt","type":["null","string"]}

static boolean isConvertibleToBeam(org.apache.avro.Schema s) {
  if (s.getType() == org.apache.avro.Schema.Type.NULL) return false;
  if (s.getType() == org.apache.avro.Schema.Type.UNION) {
    return s.getTypes().stream().allMatch(t -> t.getType() != org.apache.avro.Schema.Type.NULL || s.getTypes().size() > 1);
  }
  return true;
}

try {
  Schema beamSchema = AvroUtils.toBeamSchema(avroSchema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Can't convert 'null' to FieldType")) {
    throw new SchemaValidationException("Null-only Avro type; use ['null', concreteType] unions", e);
  }
  throw e;
}

When it happens

Trigger: Calling AvroUtils.toBeamSchema (or fromAvroSchema-based helpers) on an Avro schema whose UNION is just ['null'] or whose field type is Type.NULL directly, i.e. toFieldType()/convertLogic hitting case NULL.

Common situations: Hand-written or third-party-generated Avro schemas containing a degenerate union ['null'] with no concrete branch; schema registries returning null-only fields; code generators emitting null placeholders for optional fields.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unhandled logical type ${identifier}
• Avro only supports maps with string keys
• Unexpected type ${fieldType}
• Can't convert 'null' to non-nullable field
• Can't convert 'string' map keys to ${mapKeyType}

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