{"record":{"id":"886eaf6c3825a791","repo":"apache/beam","slug":"convert-requires-a-schema-on-the-input","errorCode":null,"errorMessage":"Convert requires a schema on the input.","messagePattern":"Convert requires a schema on the input\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/Convert.java","lineNumber":109,"sourceCode":"   */\n  public static <InputT, OutputT> PTransform<PCollection<InputT>, PCollection<OutputT>> to(\n      TypeDescriptor<OutputT> typeDescriptor) {\n    return new ConvertTransform<>(typeDescriptor);\n  }\n\n  private static class ConvertTransform<InputT, OutputT>\n      extends PTransform<PCollection<InputT>, PCollection<OutputT>> {\n    TypeDescriptor<OutputT> outputTypeDescriptor;\n\n    ConvertTransform(TypeDescriptor<OutputT> outputTypeDescriptor) {\n      this.outputTypeDescriptor = outputTypeDescriptor;\n    }\n\n    @Override\n    @SuppressWarnings(\"unchecked\")\n    public PCollection<OutputT> expand(PCollection<InputT> input) {\n      if (!input.hasSchema()) {\n        throw new RuntimeException(\"Convert requires a schema on the input.\");\n      }\n\n      SchemaCoder<InputT> coder = (SchemaCoder<InputT>) input.getCoder();\n      if (coder.getEncodedTypeDescriptor().equals(outputTypeDescriptor)) {\n        return (PCollection<OutputT>) input;\n      }\n      SchemaRegistry registry = input.getPipeline().getSchemaRegistry();\n      ConvertHelpers.ConvertedSchemaInformation<OutputT> converted =\n          ConvertHelpers.getConvertedSchemaInformation(\n              input.getSchema(), outputTypeDescriptor, registry);\n      boolean unbox = converted.unboxedType != null;\n      PCollection<OutputT> output;\n      if (converted.outputSchemaCoder != null) {\n        output =\n            input.apply(\n                ParDo.of(\n                    new DoFn<InputT, OutputT>() {\n                      @ProcessElement","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/Convert.java#L91-L127","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register a schema for the input type, e.g. with SchemaRegistry or @DefaultSchema(JavaBeanSchema.class) / AutoValueSchema on the class.","Ensure the PCollection's coder is a SchemaCoder; avoid setCoder with a non-schema coder before Convert.","Convert to/from the schema-registered type earlier in the pipeline so schema inference carries through.","Use Convert.to(TypeDescriptor) only on inputs produced by schema-aware transforms."],"exampleFix":"// before\np.apply(Create.of(new RawType()).withCoder(RawCoder.class)).apply(Convert.to(OtherType.class))\n// after\n@DefaultSchema(JavaBeanSchema.class) class RawType {...}\np.apply(Create.of(new RawType()).withCoder(SchemaCoder.of(...))).apply(Convert.to(OtherType.class))","handlingStrategy":"validation","validationCode":"if (!input.hasSchema()) throw new IllegalArgumentException(\"Input to Convert must have a schema; register one for \" + input.getCoder());","typeGuard":"boolean convertible(PCollection<?> p) { return p.hasSchema() && p.getCoder() instanceof SchemaCoder; }","tryCatchPattern":"try { return input.apply(Convert.to(Out.class)); } catch (RuntimeException e) { if (e.getMessage().contains(\"requires a schema\")) { /* register schema or abort */ } throw e; }","preventionTips":["Annotate domain classes with @DefaultSchema early in the project","Avoid overriding coders with setCoder on schema-inferred PCollections","Assert hasSchema() before applying schema transforms"],"tags":["java","apache-beam","schema","convert"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}