Resolving Gson’s “Multiple JSON Fields” Exception

1. Overview

Google Gson is a useful and flexible library for JSON data binding in Java. In most cases, Gson can perform data binding to an existing class with no modification. However, certain class structures can cause issues that are difficult to debug.

One interesting and potentially confusing exception is an IllegalArgumentException that complains about multiple field definitions:

java.lang.IllegalArgumentException: Class <YourClass> declares multiple JSON fields named <yourField> ...

This can be particularly cryptic since the Java compiler doesn’t allow multiple fields in the same class to share a name. In this tutorial, we’ll discuss the causes of this exception and learn how to get around it.

2. Exception Causes

The potential causes for this exception relate to class structure or configuration that confuses the Gson parser when serializing (or de-serializing) a class.

2.1. @SerializedName Conflicts

Gson provides the @SerializedName annotation to allow manipulation of the field name in the serialized object. This is a useful feature, but it can lead to conflicts.

For example, let’s create a simple class, BasicStudent:

public class BasicStudent {
    private String name;
    private String major;
    @SerializedName("major")
    private String concentration;
    // General getters, setters, etc.
}

During serialization, Gson will attempt to use “major” for both major and concentration, leading to the IllegalArgumentException from above:

java.lang.IllegalArgumentException: Class BasicStudent declares multiple JSON fields named 'major';
conflict is caused by fields BasicStudent#major and BasicStudent#concentration

The exception message points to the problem fields and the issue can be addressed by simply changing or removing the annotation or renaming the field.

There are also other options for excluding fields in Gson, which we’ll discuss later in this tutorial.

First, let’s look at the other cause for this exception.

2.2. Class Inheritance Hierarchies

Class inheritance can also be a source of problems when serializing to JSON. To explore this issue, we’ll need to update our student data example.

Let’s define two classes, StudentV1 and StudentV2, which extends StudentV1 and adds an additional member variable:

public class StudentV1 {
    private String firstName;
    private String lastName;
    // General getters, setters, etc.
}

public class StudentV2 extends StudentV1 {
    private String firstName;
    private String lastName;
    private String major;
    // General getters, setters, etc.
}

Notably, StudentV2 not only extends StudentV1 but also defines its own set of variables, some of which duplicate those in StudentV1. While this isn’t best practice, it’s crucial to our example and something we may encounter in the real world when using a third-party library or legacy package.

Let’s create an instance of StudentV2 and attempt to serialize it. We can create a unit test to confirm that IllegalArgumentException is thrown:

@Test
public void givenLegacyClassWithMultipleFields_whenSerializingWithGson_thenIllegalArgumentExceptionIsThrown() {
    StudentV2 student = new StudentV2("Henry", "Winter", "Greek Studies");
    Gson gson = new Gson();
    assertThatThrownBy(() -> gson.toJson(student))
      .isInstanceOf(IllegalArgumentException.class)
      .hasMessageContaining("declares multiple JSON fields named 'firstName'");
}

Similar to the @SerializedName conflicts above, Gson doesn’t know which field to use when encountering duplicate names in the class hierarchy.

3. Solutions

There are a few solutions to this issue, each with its own pros and cons that provide different levels of control over serialization.

3.1. Marking Fields as transient

The simplest way to control which fields are serialized is by using the transient field modifier. We can update BasicStudent from above:

public class BasicStudent {
    private String name;
    private transient String major;
    @SerializedName("major") 
    private String concentration; 
    // General getters, setters, etc. 
}

Let’s create a unit test to attempt serialization after this change:

@Test
public void givenBasicStudent_whenSerializingWithGson_thenTransientFieldNotSet() {
    BasicStudent student = new BasicStudent("Henry Winter", "Greek Studies", "Classical Greek Studies");
    Gson gson = new Gson();
    String json = gson.toJson(student);
    BasicStudent deserialized = gson.fromJson(json, BasicStudent.class);
    assertThat(deserialized.getMajor()).isNull();
}

Serialization succeeds, and the major field value isn’t included in the de-serialized instance.

Though this is a simple solution, there are two downsides to this approach. Adding transient means the field will be excluded from all serialization, including basic Java serialization. This approach also assumes that BasicStudent can be modified, which may not always be the case.

3.2. Serialization With Gson’s @Expose Annotation

If the problem class can be modified and we want an approach scoped to only Gson serialization, we can make use of the @Expose annotation. This annotation informs Gson which fields should be exposed during serialization, de-serialization, or both.

We can update our StudentV2 instance to explicitly expose only its fields to Gson:

public class StudentV2 extends StudentV1 {
    @Expose
    private String firstName;
    @Expose 
    private String lastName; 
    @Expose
    private String major;
    // General getters, setters, etc. 
}

If we run the code again, nothing will change, and we’ll still see the exception. By default, Gson doesn’t change its behavior when encountering @Expose – we need to tell the parser what it should do.

Let’s update our unit test to use the GsonBuilder to create an instance of the parser that excludes fields without @Expose:

@Test
public void givenStudentV2_whenSerializingWithGsonExposeAnnotation_thenSerializes() {
    StudentV2 student = new StudentV2("Henry", "Winter", "Greek Studies");
    Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create();
    String json = gson.toJson(student);
    assertThat(gson.fromJson(json, StudentV2.class)).isEqualTo(student);
}

Serialization and de-serialization now succeed. @Expose has the benefit of still being a simple solution while only affecting Gson serialization (and only if we configure the parser to recognize it).

This approach still assumes we can edit the source code, however. It also doesn’t provide much flexibility – all fields that we care about need to be annotated, and the rest are excluded from both serialization and de-serialization.

3.3. Serialization With Gson’s ExclusionStrategy

Fortunately, Gson provides a solution when we can’t change the source class or we need more flexibility: the ExclusionStrategy.

This interface informs Gson of how to exclude fields during serialization or de-serialization and allows for more complex business logic. We can declare a simple ExclusionStrategy implementation:

public class StudentExclusionStrategy implements ExclusionStrategy {
    @Override
    public boolean shouldSkipField(FieldAttributes field) {
        return field.getDeclaringClass() == StudentV1.class;
    }
    @Override
    public boolean shouldSkipClass(Class<?> aClass) {
        return false;
    }
}

The ExclusionStrategy interface has two methods: shouldSkipField() provides granular control at the individual field level, and shouldSkipClass() controls if all fields of a certain type should be skipped. In our example above, we’re starting simple and skipping all fields from StudentV1.

Just as with @Expose, we need to tell Gson how to use this strategy. Let’s configure it in our test:

@Test
public void givenStudentV2_whenSerializingWithGsonExclusionStrategy_thenSerializes() {
    StudentV2 student = new StudentV2("Henry", "Winter", "Greek Studies");
    Gson gson = new GsonBuilder().setExclusionStrategies(new StudentExclusionStrategy()).create();
    assertThat(gson.fromJson(gson.toJson(student), StudentV2.class)).isEqualTo(student);
}

It’s worth noting that we’re configuring the parser with setExclusionStrategies() – this means our strategy is used for both serialization and de-serialization.

If we wanted more flexibility of when the ExclusionStrategy is applied, we could configure the parser differently:

// Only exclude during serialization
Gson gson = new GsonBuilder().addSerializationExclusionStrategy(new StudentExclusionStrategy()).create();
// Only exclude during de-serialization
Gson gson = new GsonBuilder().addDeserializationExclusionStrategy(new StudentExclusionStrategy()).create();

This approach is slightly more complex than our other two solutions: we needed to declare a new class and think more about what makes a field important to include. We kept the business logic in our ExclusionStrategy fairly simple for this example, but the upside of this approach is richer and more robust field exclusion. Finally, we didn’t need to change the code inside StudentV2 or StudentV1.

4. Conclusion

In this article, we discussed the causes for a tricky yet ultimately fixable IllegalArgumentException we can encounter when using Gson.

We found that there are a variety of solutions we can implement based on our needs for simplicity, granularity, and flexibility.

As always, all of the code can be found over on GitHub.