google/gson · error · JsonIOException

@SerializedName on " + methodDescription + " is not supporte

Error message

@SerializedName on " + methodDescription + " is not supported

What it means

Thrown during record adapter construction when a record accessor method carries @SerializedName but the backing field does not. Gson cannot reliably distinguish an inherited implicit annotation from an explicit one on the accessor, so it rejects this combination as a JsonIOException. The field must own the annotation.

Source

Thrown at gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java:383

          // GsonBuilder.excludeFieldsWithModifiers can overwrite this.
          if (Modifier.isStatic(field.getModifiers())) {
            deserialize = false;
          } else {
            accessor = ReflectionHelper.getAccessor(raw, field);
            // If blockInaccessible, skip and perform access check later
            if (!blockInaccessible) {
              ReflectionHelper.makeAccessible(accessor);
            }

            // @SerializedName can be placed on accessor method, but it is not supported there
            // If field and method have annotation it is not easily possible to determine if
            // accessor method is implicit and has inherited annotation, or if it is explicitly
            // declared with custom annotation
            if (accessor.getAnnotation(SerializedName.class) != null
                && field.getAnnotation(SerializedName.class) == null) {
              String methodDescription =
                  ReflectionHelper.getAccessibleObjectDescription(accessor, false);
              throw new JsonIOException(
                  "@SerializedName on " + methodDescription + " is not supported");
            }
          }
        }

        // If blockInaccessible, skip and perform access check later
        // For Records if the accessor method is used the field does not have to be made accessible
        if (!blockInaccessible && accessor == null) {
          ReflectionHelper.makeAccessible(field);
        }

        Type fieldType = GsonTypes.resolve(type.getType(), raw, field.getGenericType());
        List<String> fieldNames = getFieldNames(field);
        String serializedName = fieldNames.get(0);
        BoundField boundField =
            createBoundField(
                context,
                field,

View on GitHub (pinned to 8b8628c656)

Solutions

Move @SerializedName from the accessor method to the record component (field).
Remove the annotation from the accessor if the default name is acceptable.
Use a custom TypeAdapter if you genuinely need method-level name control.

Example fix

// before
public record Item(@SerializedName("i") int id) {
  @SerializedName("i") public int id() { return id; }
}

// after: annotation lives on the component only
public record Item(@SerializedName("i") int id) {}

Defensive patterns

Strategy: validation

Validate before calling

// Reject records whose accessor carries @SerializedName without the field
for (Method m : MyRecord.class.getDeclaredMethods()) {
  if (m.isAnnotationPresent(SerializedName.class)) {
    Field f = MyRecord.class.getDeclaredField(m.getName());
    if (!f.isAnnotationPresent(SerializedName.class)) {
      throw new IllegalStateException("Move @SerializedName to component " + m.getName());
    }
  }
}

Type guard

null

Try / catch

null

Prevention

When migrating to records, move all method-level annotations to the components.
Code-review record declarations for stray accessor annotations.
Add a lint/test that builds a Gson instance with every record type to fail fast at startup.

When it happens

Trigger: A developer explicitly annotates a record's accessor method (e.g., `@SerializedName("x") public String name()`) instead of the component field. Detected in getBoundFields (line 379) when accessor.getAnnotation(SerializedName.class) != null && field.getAnnotation(SerializedName.class) == null.

Common situations: Migrating POJOs to records and carrying over method-level annotations; tooling/IDE auto-adding annotations to accessors; confusion about whether records accept @SerializedName on accessors.

Related errors

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/d4eb7c01a640b4d9.json. Report an issue: GitHub.