apache/beam · error · IllegalArgumentException

For GenericRecord, please call readAvroGenericRecords

Error message

For GenericRecord, please call readAvroGenericRecords

What it means

readAvrosWithBeamSchema(Class) is meant for generated Avro classes (specific records). GenericRecord is schema-less at the type level, so the API explicitly rejects it and directs users to readAvroGenericRecords, where the Avro schema is supplied explicitly.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubIO.java:749

        .setCoder(
            SchemaCoder.of(
                schema,
                TypeDescriptor.of(GenericRecord.class),
                AvroUtils.getToRowFunction(GenericRecord.class, avroSchema),
                AvroUtils.getFromRowFunction(GenericRecord.class)))
        .build();
  }

  /**
   * Returns a {@link PTransform} that continuously reads binary encoded Avro messages of the
   * specific type.
   *
   * <p>Beam will infer a schema for the Avro schema. This allows the output to be used by SQL and
   * by the schema-transform library.
   */
  public static <T> Read<T> readAvrosWithBeamSchema(Class<T> clazz) {
    if (clazz.equals(GenericRecord.class)) {
      throw new IllegalArgumentException("For GenericRecord, please call readAvroGenericRecords");
    }
    AvroCoder<T> coder = AvroCoder.of(clazz);
    org.apache.avro.Schema avroSchema = coder.getSchema();
    Schema schema = AvroUtils.getSchema(clazz, avroSchema);
    if (schema == null) {
      throw new IllegalArgumentException("Could not infer Beam schema for class: " + clazz);
    }
    return Read.newBuilder(parsePayloadUsingCoder(coder))
        .setCoder(
            SchemaCoder.of(
                schema,
                TypeDescriptor.of(clazz),
                AvroUtils.getToRowFunction(clazz, avroSchema),
                AvroUtils.getFromRowFunction(clazz)))
        .build();
  }

  /** Returns A {@link PTransform} that writes to a Google Cloud Pub/Sub stream. */

View on GitHub (pinned to 12126d8942)

Solutions

Call PubsubIO.readAvroGenericRecords(avroSchema) passing your org.apache.avro.Schema instead.
Alternatively generate a specific Avro class (avro-maven-plugin/avro-tools) and pass that class to readAvrosWithBeamSchema.

Example fix

// before
PubsubIO.readAvrosWithBeamSchema(GenericRecord.class);
// after
PubsubIO.readAvroGenericRecords(new Schema.Parser().parse(schemaJson));

Defensive patterns

Strategy: type-guard

Validate before calling

if (clazz == GenericRecord.class) {
  return PubsubIO.readAvroGenericRecords(schema);
}
return PubsubIO.readAvrosWithBeamSchema(clazz);

Type guard

static <T> PubsubIO.Read<T> pickReader(Class<T> clazz, org.apache.avro.Schema schema) {
  if (clazz.equals(GenericRecord.class)) {
    throw new IllegalArgumentException("Use readAvroGenericRecords(schema) for GenericRecord");
  }
  return null; // caller uses readAvrosWithBeamSchema(clazz)
}

Try / catch

try {
  return PubsubIO.readAvrosWithBeamSchema(clazz);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("please call readAvroGenericRecords"))
    throw new UsageException("Use PubsubIO.readAvroGenericRecords(avroSchema) for GenericRecord", e);
  throw e;
}

Prevention

Never pass GenericRecord.class to class-based Avro readers
Document which reader variant your team uses for schema-less records
Add a compile-time-style helper that dispatches on the class

When it happens

Trigger: Calling PubsubIO.readAvrosWithBeamSchema(GenericRecord.class) or any variable typed as GenericRecord.class.

Common situations: Developers who don't have generated Avro classes reaching for the generic reader with GenericRecord.class instead of the Avro-schema-based variant.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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