apache/beam · error · IllegalArgumentException

Could not infer Beam schema for class: {clazz}

Error message

Could not infer Beam schema for class: {clazz}

What it means

readAvrosWithBeamSchema(clazz) asks AvroUtils.getSchema to derive a Beam Schema from the Avro class. If it returns null (the Avro-generated class cannot be mapped to a Beam schema), this IllegalArgumentException is thrown.

Source

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

        .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. */
  public static Write<PubsubMessage> writeMessages() {
    return Write.newBuilder()
        .setTopicProvider(null)
        .setTopicFunction(null)
        .setDynamicDestinations(false)
        .build();

View on GitHub (pinned to 12126d8942)

Solutions

  1. Regenerate the Avro class with a current avro-tools/avro-maven-plugin version so the schema is Beam-mappable.
  2. Simplify unsupported fields (e.g. replace exotic logical types with string/long) in the .proto—rather the .avsc—and regenerate.
  3. Fall back to readAvroGenericRecords(schema) plus manual mapping into a typed PCollection.

Example fix

// before
PubsubIO.readAvrosWithBeamSchema(LegacyEvent.class); // schema not mappable
// after (regenerated class with supported types)
PubsubIO.readAvrosWithBeamSchema(com.example.generated.Event.class);
Defensive patterns

Strategy: validation

Validate before calling

Schema beamSchema = AvroUtils.getSchema(clazz, AvroCoder.of(clazz).getSchema());
if (beamSchema == null) {
  throw new IllegalArgumentException("Beam cannot map Avro class " + clazz + "; regenerate with supported types");
}
PubsubIO.readAvrosWithBeamSchema(clazz);

Type guard

boolean beamCanMapClass(Class<?> clazz) {
  return AvroUtils.getSchema(clazz, AvroCoder.of(clazz).getSchema()) != null;
}

Try / catch

try {
  return PubsubIO.readAvrosWithBeamSchema(clazz);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Could not infer Beam schema for class"))
    throw new ConfigException("Avro class not Beam-schema mappable: " + clazz, e);
  throw e;
}

Prevention

When it happens

Trigger: Passing a class whose Avro schema contains types Beam cannot map (unsupported logical types), or a non-Avro-generated class (though AvroCoder.of may fail earlier), to readAvrosWithBeamSchema.

Common situations: Using Avro classes generated with unusual compiler settings or older avro-tools versions producing unmappable fields; classes with reflective/union-typed fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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