Gson Appendix — 5 Common Mistakes & Issues

In the past 30+ blog posts we've shown you almost every little detail about Gson. It's time to take a step back and look at the big picture. In this blog post, we'll go through some common mistakes & issues you'll run into when using Gson in your production apps.

Of course, this will not be the only post in our Gson series. If you're interested in the other topics, check out our series outline:

Gson Series Overview

1. Expecting an Object Instead of an Array

Most Gson developers will see java.lang.IllegalStateException: Expected BEGIN_OBJECT but was BEGIN_ARRAY at line 1 column 2 path $ at some point in their life when deserializing data.

It simply tells you that the JSON contains an array wrapped in [] and your model expects an object at that spot. If it's line 1 and a low column number, it's usually your entire model, which should be a single object instead of a Java array. If it's a higher line it might be a nested element in your model.

We recommend to take a closer look at the JSON and compare it to your Java model. You could also compare the result of a tool like jsonschema2pojo with your model setup. You'll find the mistake eventually.

2. Expecting an Array Instead of an Object

Flipping our previous example will be something you can run into as well. If your model describes an array, but the JSON contains a single object wrapped in {}, Gson will throw java.lang.IllegalStateException: Expected BEGIN_ARRAY but was BEGIN_OBJECT at line 1 column 2 path $.

The approach to fix this is the same. Control your Java model setup and the JSON to find the difference. Once both have the same data structure Gson will work without any issues again.

3. Not Re-Using Your Gson Instance

Almost all of our blog posts contain code snippets like this:

UserSimple userObject = new UserSimple("Norman", "", 26, true);

Gson gson = new Gson();  
String userJson = gson.toJson(userObject);  

One easy way to optimize your performance is to share you Gson instance across a class. You don't need to create a new Gson instance for every single conversion. You could declare it as a field property and let all the methods you've written re-use it. This gives your application a little bit of extra performance.

4. Not Minifying Your Serialized Data

Gson is very friendly to us as developers. It often serializes and deserializes the data without any additional configuration. Even if it works out of the box, don't let that stop you from further optimization!

For example, in a lot of apps the Java model is way more complex than the server actually expects. The app will send more data than the server will process. This costs unnecessary performance, since Gson has to do unneeded conversions.

If your app is sending data over the Internet, it also creates larger strings that make the requests take longer and eat up your user's data plan.

We recommend that you double check what you're sending and, if possible, minimize your app's serialized data. Our blog post on exclusion strategies should provide you with all the necessary knowledge.

5. Using Custom Setters

As we've explained multiple times, Gson relies on reflection and won't use your custom getters & setters. If your model classes have logic in their setters, you'll run into some problems:

public void setFirstName(String firstName) {  
    this.firstName = firstName;


But no worries, we've shown you in the second custom deserializer post how you can work with logic in your setters.


In this blog post, you've learned a few key things that can cause issues when using the Gson library. Make sure you're aware of them as you progress through your development phase.

If you've feedback or a question, let us know in the comments or on twitter @futurestud_io.

Make it rock & enjoy coding!

Explore the Library

Find interesting tutorials and solutions for your problems.