apache/beam · error · RuntimeException

Convert requires a schema on the input.

Error message

Convert requires a schema on the input.

What it means

The Convert transform converts between a PCollection's schema type and another type via its registered schema. It requires the input PCollection to have a schema (SchemaCoder); without one there is no SchemaRegistry mapping to perform the conversion, so expand() throws immediately.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/Convert.java:109

   */
  public static <InputT, OutputT> PTransform<PCollection<InputT>, PCollection<OutputT>> to(
      TypeDescriptor<OutputT> typeDescriptor) {
    return new ConvertTransform<>(typeDescriptor);
  }

  private static class ConvertTransform<InputT, OutputT>
      extends PTransform<PCollection<InputT>, PCollection<OutputT>> {
    TypeDescriptor<OutputT> outputTypeDescriptor;

    ConvertTransform(TypeDescriptor<OutputT> outputTypeDescriptor) {
      this.outputTypeDescriptor = outputTypeDescriptor;
    }

    @Override
    @SuppressWarnings("unchecked")
    public PCollection<OutputT> expand(PCollection<InputT> input) {
      if (!input.hasSchema()) {
        throw new RuntimeException("Convert requires a schema on the input.");
      }

      SchemaCoder<InputT> coder = (SchemaCoder<InputT>) input.getCoder();
      if (coder.getEncodedTypeDescriptor().equals(outputTypeDescriptor)) {
        return (PCollection<OutputT>) input;
      }
      SchemaRegistry registry = input.getPipeline().getSchemaRegistry();
      ConvertHelpers.ConvertedSchemaInformation<OutputT> converted =
          ConvertHelpers.getConvertedSchemaInformation(
              input.getSchema(), outputTypeDescriptor, registry);
      boolean unbox = converted.unboxedType != null;
      PCollection<OutputT> output;
      if (converted.outputSchemaCoder != null) {
        output =
            input.apply(
                ParDo.of(
                    new DoFn<InputT, OutputT>() {
                      @ProcessElement

View on GitHub (pinned to 12126d8942)

Solutions

1. Register a schema for the input type, e.g. with SchemaRegistry or @DefaultSchema(JavaBeanSchema.class) / AutoValueSchema on the class.
2. Ensure the PCollection's coder is a SchemaCoder; avoid setCoder with a non-schema coder before Convert.
3. Convert to/from the schema-registered type earlier in the pipeline so schema inference carries through.
4. Use Convert.to(TypeDescriptor) only on inputs produced by schema-aware transforms.

Example fix

// before
p.apply(Create.of(new RawType()).withCoder(RawCoder.class)).apply(Convert.to(OtherType.class))
// after
@DefaultSchema(JavaBeanSchema.class) class RawType {...}
p.apply(Create.of(new RawType()).withCoder(SchemaCoder.of(...))).apply(Convert.to(OtherType.class))

if (!input.hasSchema()) throw new IllegalArgumentException("Input to Convert must have a schema; register one for " + input.getCoder());

boolean convertible(PCollection<?> p) { return p.hasSchema() && p.getCoder() instanceof SchemaCoder; }

try { return input.apply(Convert.to(Out.class)); } catch (RuntimeException e) { if (e.getMessage().contains("requires a schema")) { /* register schema or abort */ } throw e; }

When it happens

Trigger: Applying Convert.to()/from() to a PCollection whose element type was never registered with a schema — e.g. a PCollection created from a raw coder (Create.of with a non-schema Java type, side-input derived without schema inference) so input.hasSchema() is false.

Common situations: Using Convert on POJOs lacking schema registration (no @DefaultSchema/POJO or Avro registration), or on PCollections whose coder was overridden with a non-schema coder, breaking the schema inference chain.

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

• Cannot provide a coder for a Beam Row. Please provide a sche
• Failed to decode Schema due to an error decoding Field proto
• Encountered UNSPECIFIED AtomicType
• Null type descriptor on input.
• Exploded field %s must be an iterable type, got %s.

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