apache/beam · error · RuntimeException

@SchemaFieldName can only be used on getters in Java Beans.

Error message

@SchemaFieldName can only be used on getters in Java Beans. Found on setter '%s'

What it means

Thrown by JavaBeanSchema.get when a setter method carries @SchemaFieldName. JavaBean schema naming annotations must be placed on getters; a name override on a setter is ambiguous and rejected at schema-registration time.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/JavaBeanSchema.java:126

    public List<FieldValueTypeInformation> get(TypeDescriptor<?> typeDescriptor) {
      return ReflectUtils.getMethods(typeDescriptor.getRawType()).stream()
          .filter(ReflectUtils::isSetter)
          .filter(m -> !m.isAnnotationPresent(SchemaIgnore.class))
          .map(m -> FieldValueTypeInformation.forSetter(typeDescriptor, m))
          .map(
              t -> {
                Method m =
                    Preconditions.checkNotNull(
                        t.getMethod(), JavaBeanUtils.SETTER_WITH_NULL_METHOD_ERROR);
                if (m.getAnnotation(SchemaFieldNumber.class) != null) {
                  throw new RuntimeException(
                      String.format(
                          "@SchemaFieldNumber can only be used on getters in Java Beans. Found on"
                              + " setter '%s'",
                          m.getName()));
                }
                if (m.getAnnotation(SchemaFieldName.class) != null) {
                  throw new RuntimeException(
                      String.format(
                          "@SchemaFieldName can only be used on getters in Java Beans. Found on"
                              + " setter '%s'",
                          m.getName()));
                }
                if (m.getAnnotation(SchemaCaseFormat.class) != null) {
                  throw new RuntimeException(
                      String.format(
                          "@SchemaCaseFormat can only be used on getters in Java Beans. Found on"
                              + " setter '%s'",
                          m.getName()));
                }
                return t;
              })
          .collect(Collectors.toList());
    }

    @Override

View on GitHub (pinned to 12126d8942)

Solutions

1. Move @SchemaFieldName from the setter to the corresponding getter.
2. Remove the annotation from the setter; field naming is defined only via getters in Java Beans.

Example fix

// before
@SchemaFieldName("user_name")
public void setName(String name) { ... }

// after
public void setName(String name) { ... }
// (keep @SchemaFieldName("user_name") on getName())

for (Method m : clazz.getMethods()) { if (m.getParameterCount() == 1 && m.isAnnotationPresent(SchemaFieldName.class)) { throw new IllegalStateException("@SchemaFieldName must be on the getter, not setter " + m.getName()); } }

try { schemaOf(clazz); } catch (RuntimeException e) { if (e.getMessage().contains("@SchemaFieldName can only be used on getters")) { /* move annotation to getter */ } else { throw e; } }

When it happens

Trigger: Annotating a setter with @SchemaFieldName; schema introspection of the bean walks setter methods and throws when it detects the annotation.

Common situations: Duplicating annotations on both accessor halves; generated beans emitting annotations on setters; refactoring that moved getters/setters without moving annotations.

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

• @SchemaFieldNumber can only be used on getters in Java Beans
• Cannot define both @SchemaFieldName and @SchemaCaseFormat. F
• Getter has wrong prefix <method>
• Setter methods should take a single argument <method>
• Setter has wrong prefix <method>

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