How to fix "expected begin_array but was begin_object" in Retrofit ?

Before we begin, keep this in mind

begin_array means the json response is an array which will look something like this [{},{},..]
begin_object means the json response is an object which will look something like this {....}

gson is one cool library that will provide us with cool tips in the form of errors while handling json responses. One such tip is "expected begin_array but was begin_object". These tips/errors are quite self explanatory, we can now look deeper into these errors.

While handling responses using retrofit, we often tend to come across an error "expected begin_array but was begin_object", which is thrown by gson. Obviously this means that we are trying to parse the response as if it is a json array response but when actually it is a json object response. But still we come across these errors a lot of time. We will be looking in detail about such situations in this post.

First add the following dependencies in your app's build.gradle file

compile 'com.squareup.retrofit2:retrofit:2.3.0'
compile 'com.squareup.retrofit2:converter-gson:2.3.0'


  • json object  response is of the form {....}.  The json object may also contain a json array like the below example where the json object contains a json array named user_array.
"user_array": [
 }, {..},

In order to parse the above json object you can either use the JsonObject from gson or create pojo classes

1. Parsing using JsonObject  from gson

Retrofit retrofit = new Retrofit.Builder() .baseUrl("base_url") .addConverterFactory(GsonConverterFactory.create()) .build(); RequestInterface request = retrofit.create(RequestInterface.class); Call<JsonObject> call=request.getJson(); call.enqueue(new Callback<JsonObject>() { @Override public void onResponse(Call<JsonObject> call, Response<JsonObject> response) { progressDialog.dismiss(); String s= String.valueOf(response.get("username")); JsonArray user_array= response.getAsJsonArray("user_array"); Toast.makeText(PrintTicket.this,response.toString(),Toast.LENGTH_SHORT).show(); } @Override public void onFailure(Call<JsonObject> call, Throwable t) { progressDialog.dismiss(); Toast.makeText(PrintTicket.this,t.toString(),Toast.LENGTH_SHORT).show(); } });
public interface RequestInterface { @GET("api_endpoint") Call<JsonObject> getJson(); }

2. Parsing using POJO  class

You can automatically generate the pojo classes by pasting your json response structure in .

FYI : after pasting the response structure in ,  set the source type to JSON and Annotation style to Gson , now click preview button and you can see generated pojo class/classes

For the above case you will need to generate two classes like below

public class Example {

private String username;
private String email;
private List<UserArray> userArray = null;

public String getUsername() {
return username;

public void setUsername(String username) {
this.username = username;

public String getEmail() {
return email;

public void setEmail(String email) { = email;

public List<UserArray> getUserArray() {
return userArray;

public void setUserArray(List<UserArray> userArray) {
this.userArray = userArray;


public class UserArray {

private String userAddress;
private String userLocation;

public String getUserAddress() {
return userAddress;

public void setUserAddress(String userAddress) {
this.userAddress = userAddress;

public String getUserLocation() {
return userLocation;

public void setUserLocation(String userLocation) {
this.userLocation = userLocation;


In the above  pojo classes, we have used @SerializedName annotation which will help us to map the class variables to respective keys in the response json. For example, in, the string variable userAddress is correctly mapped to user_address by using the @SerializedName annotation like this

private String userAddress;

The is for parsing the outer json object whereas is for parsing the inner json object which should be parsed as a list(since there is a list of objects in user_array)

Now the retrofit call should be made like the following

ArrayList<RouteStop> user_array;
Retrofit retrofit = new Retrofit.Builder()

RequestInterface request = retrofit.create(RequestInterface.class);
Call<Example> call=request.getJson();
call.enqueue(new Callback<Example>() {
    public void onResponse(Call<Example> call, Response<Example> response) {
        String user_name= response.getUsername();
        user_array= new ArrayList<>(response.getUserArray());

    public void onFailure(Call<Example> call, Throwable t) {
public interface RequestInterface {
Call<Example> getJson();

The error "expected begin_array but was begin_object" occurs  if you are trying to parse the above response using Call<List<Example>> call=request.getJson(); because by using <List<Example>> we are clearly making an array request but we need to make an object request since response is of the form {..}

Similarly we get the error "expected begin_object but was begin_array when we are trying to make an object request were the response is of the form [{},{},..], which is a json array example. In such case we should make the call like Call<List<Example>>

Please check this tutorial to parse json array and display it in a recyclerview. Also free source code download is avalaible.

You may also check similar issues in StackOverflow

You may also check the following video that shows how to parse a json response using retrofit 2


  1. thanks...this was very informative

  2. Thanks! Your article was really helpful

    1. really glad it helped, thanks for leaving the feedback

    2. This article really helped me understand Retrofit more clearly as well as solving the problem which I was facing.Thanks a lot, Keep the good work going.