apache/beam · error · InvalidParameterException

A method marked with SchemaCreate in class {} does not retur

Error message

A method marked with SchemaCreate in class {} does not return a type assignable to {}

What it means

ReflectUtils.getAnnotatedCreateMethod searches a class for a static method annotated with @SchemaCreate and verifies that its return type is assignable to the class itself. If a @SchemaCreate method returns an incompatible type, this InvalidParameterException is thrown, since such a method could not be used to create instances of the class.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/ReflectUtils.java:136

        .filter(m -> m.getAnnotation(SchemaCreate.class) != null)
        .findFirst()
        .orElse(null);
  }

  public static @Nullable Method getAnnotatedCreateMethod(Class<?> clazz) {
    return ANNOTATED_CONSTRUCTORS.computeIfAbsent(
        clazz,
        c -> {
          Method method =
              Arrays.stream(clazz.getDeclaredMethods())
                  .filter(m -> !Modifier.isPrivate(m.getModifiers()))
                  .filter(m -> !Modifier.isProtected(m.getModifiers()))
                  .filter(m -> Modifier.isStatic(m.getModifiers()))
                  .filter(m -> m.getAnnotation(SchemaCreate.class) != null)
                  .findFirst()
                  .orElse(null);
          if (method != null && !clazz.isAssignableFrom(method.getReturnType())) {
            throw new InvalidParameterException(
                "A method marked with SchemaCreate in class "
                    + clazz
                    + " does not return a type assignable to "
                    + clazz);
          }
          return method;
        });
  }

  // Get all public, non-static, non-transient fields.
  public static List<Field> getFields(Class<?> clazz) {
    return DECLARED_FIELDS.computeIfAbsent(
        clazz,
        c -> {
          Map<String, Field> types = new LinkedHashMap<>();
          do {
            if (c.getPackage() != null && c.getPackage().getName().startsWith("java.")) {
              break; // skip java built-in classes

View on GitHub (pinned to 12126d8942)

Solutions

Change the @SchemaCreate method's return type to the annotated class (or a subtype assignable to it).
Remove @SchemaCreate from methods that are not intended as creators.
If creating via a different concrete type, annotate the correct target class instead and register that type with the schema.

Example fix

// before
class Order {
  @SchemaCreate
  public static OrderBuilder builder() { ... } // returns wrong type
}
// after
class Order {
  @SchemaCreate
  public static Order create(String id) { return new Order(id); }
}

Defensive patterns

Strategy: validation

Validate before calling

for (Method m : MyPojo.class.getDeclaredMethods()) {
  if (m.isAnnotationPresent(org.apache.beam.sdk.schemas.SchemaCreate.class)
      && !MyPojo.class.isAssignableFrom(m.getReturnType())) {
    throw new IllegalStateException("@SchemaCreate method " + m + " must return MyPojo");
  }
}

Try / catch

try {
  Method m = ReflectUtils.getAnnotatedCreateMethod(MyPojo.class, MyPojo.class, SchemaCreate.class);
} catch (InvalidParameterException e) {
  // fix the @SchemaCreate method's return type and retry
}

Prevention

Only annotate static factory methods whose return type is exactly the annotated class.
Grep for @SchemaCreate in code review to verify return types.
Cover @SchemaCreate usage in unit tests so mismatched return types fail fast.

When it happens

Trigger: Annotating a static method with @SchemaCreate whose declared return type is not the class itself (or a subtype), e.g. a factory returning a builder, a different class, or void.

Common situations: Copy-pasting @SchemaCreate onto helper/static methods, annotating a method that returns a common interface not implemented by the annotated class's hierarchy, or moving the annotation during refactoring.

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

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