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.

Solutions

1. Call PubsubIO.readAvroGenericRecords(avroSchema) passing your org.apache.avro.Schema instead.
2. 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));

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

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 {
  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;
}

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

• AVRO schema doesn't match row schema. Row schema
• Could not decode avro record from given bytes
• Could not encode avro from given row
• Could not infer Beam schema for class
• Could not infer Beam schema from Avro schema

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

Appendix: 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)