apache/beam · error · IllegalStateException

Cannot call getSchema when there is no schema

Error message

Cannot call getSchema when there is no schema

What it means

This IllegalStateException is thrown by PCollection.getSchema() when the PCollection has no schema attached. In Beam, schemas are only present if the coder is a SchemaCoder (set via setSchema or schema-aware transforms); calling getSchema on a plain-coded PCollection is an invalid state, so the library fails fast instead of returning null.

Solutions

  1. Verify with pc.hasSchema() before calling getSchema()
  2. Attach a schema via pc.setSchema(schema, toRowFn, fromRowFn) or use schema-aware transforms like setRowSchema/TypedSchemaTransform output
  3. Convert the element type to a schema-registered class (Java beans, @DefaultSchema annotated types) so the coder becomes a SchemaCoder
  4. Use getCoder() and check instanceof SchemaCoder to access the schema manually

Example fix

// before
Schema schema = pc.getSchema(); // IllegalStateException
// after
if (pc.hasSchema()) {
  Schema schema = pc.getSchema();
} else {
  pc = pc.setRowSchema(MyBean.class.getDeclaredSchema());
}
Defensive patterns

Strategy: validation

Validate before calling

if (!pc.hasSchema()) { throw new IllegalStateException("PCollection has no schema; call setSchema first"); }

Type guard

boolean hasSchema(PCollection<?> pc) { return pc.hasSchema(); }

Try / catch

try { Schema s = pc.getSchema(); } catch (IllegalStateException e) { /* attach schema or fallback */ }

Prevention

When it happens

Trigger: Calling getSchema(), or any caller that delegates to it (schema(), converted(), keySchema(), inputSchema(), addFieldsInformation()), on a PCollection whose coder is not a SchemaCoder — e.g. a PCollection created from Create.of with simple types, or output of a transform that did not call setSchema.

Common situations: Expecting a schema after a ParDo/MapElements that produces plain types; using schema helpers (rows(), recordClass()) on collections from non-schema-aware sources; forgetting to apply FieldAccessDescriptor/schema registration before schema-based operations.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollection.java:325

  /** Sets a {@link Schema} on this {@link PCollection}. */
  public PCollection<T> setSchema(
      Schema schema,
      TypeDescriptor<T> typeDescriptor,
      SerializableFunction<T, Row> toRowFunction,
      SerializableFunction<Row, T> fromRowFunction) {
    return setCoder(SchemaCoder.of(schema, typeDescriptor, toRowFunction, fromRowFunction));
  }

  /** Returns whether this {@link PCollection} has an attached schema. */
  public boolean hasSchema() {
    return coderOrFailure.coder != null && coderOrFailure.coder instanceof SchemaCoder;
  }

  /** Returns the attached schema. */
  public Schema getSchema() {
    if (!hasSchema()) {
      throw new IllegalStateException("Cannot call getSchema when there is no schema");
    }
    return ((SchemaCoder) getCoder()).getSchema();
  }

  /** Returns the attached schema's toRowFunction. */
  public SerializableFunction<T, Row> getToRowFunction() {
    if (!hasSchema()) {
      throw new IllegalStateException("Cannot call getToRowFunction when there is no schema");
    }
    return ((SchemaCoder<T>) getCoder()).getToRowFunction();
  }

  /** Returns the attached schema's fromRowFunction. */
  public SerializableFunction<Row, T> getFromRowFunction() {
    if (!hasSchema()) {
      throw new IllegalStateException("Cannot call getFromRowFunction when there is no schema");
    }
    return ((SchemaCoder<T>) getCoder()).getFromRowFunction();

View on GitHub (pinned to 12126d8942)