Course – LS (cat=JSON/Jackson)

Get started with Spring and Spring Boot, through the Learn Spring course:


1. Overview

In this tutorial, we’ll discuss some common Gson errors and how to fix them.

2. The Gson Library

Gson is a Java library developed by Google that allows converting Java objects to JSON and vice versa. It simplifies serialization and deserialization tasks, providing customization options and efficient performance for handling complex object structures.

The latest version of the Gson library can be found in the Maven Central Repository. Let’s add the dependency to our pom.xml:


3. Get an Array While Expecting an Object

First, let’s define a simple Person object with a lone name attribute:

public class Person {

    public String name;

    // standard constructor and getter


Let’s now consider a JSONArray of two persons named James and John:

    "name": "John"
    "name": "James"

What if we try by mistake to parse this JSONArray into a simple Person object? We’d do this via the following instruction:

Person person = new Gson().fromJson("[{\"name\":\"John\"},{\"name\":\"James\"}]", Person.class);

When running this code, we get the following Exception: java.lang.IllegalStateException: Expected BEGIN_OBJECT but was BEGIN_ARRAY at line 1 column 2 path $

It’s indeed impossible to parse a JSONArray into a lone Object. To fix this error, we should parse it into an array or a Collection instead. Parsing into an array is very straightforward:

Person[] personArray = new Gson().fromJson("[{\"name\":\"John\"},{\"name\":\"James\"}]", Person[].class)

However, parsing into a Collection requires some preliminary work. We need to define the target Type beforehand:

Type collectionType = new TypeToken<Collection<Person>>() {}.getType();
Collection<Person> personCollection = new Gson().fromJson("[{\"name\":\"John\"},{\"name\":\"James\"}]", collectionType);

4. Get an Object While Expecting an Array

On the other hand, let’s now define the following Person named John:

  "name": "John"

Let’s try to parse this JSONObject into a Java array:

Person[] personArray = new Gson().fromJson("{\"name\":\"John\"}", Person[].class);

This code throws the following JsonSyntaxException: java.lang.IllegalStateException: Expected BEGIN_ARRAY but was BEGIN_OBJECT at line 1 column 2 path $

The error message indicates to us that we should parse the input into a lone Object:

Person person = new Gson().fromJson("{\"name\":\"John\"}", Person.class);

5. Conclusion

In this article, we learned about common mistakes made while using Gson for object deserialization. Incorrectly trying to match an array with an Object, or the contrary, will always lead to an error.

As always, the source code for the examples is available over on GitHub.

Course – LS (cat=JSON/Jackson)

Get started with Spring and Spring Boot, through the Learn Spring course:

res – REST with Spring (eBook) (everywhere)
Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.