Introduction

This Gson error means your Java type does not match the JSON structure being parsed. Gson expected a single JSON object, but the input actually starts with a JSON array, so the fix is to change either the JSON or the target Java type.

What the Error Really Means

If the JSON begins with a left square bracket, then the payload is an array:

1[
2  {"id": 1, "name": "Ana"},
3  {"id": 2, "name": "Ben"}
4]

If your code tries to parse that into one object:

User user = gson.fromJson(json, User.class);

Gson complains because User.class describes one object, not a list of objects.

That is exactly what "Expected BEGIN_OBJECT but was BEGIN_ARRAY" means.

Fix 1: Parse into a List

If the payload is truly an array, parse it into a collection.

1import com.google.gson.Gson;
2import com.google.gson.reflect.TypeToken;
3import java.lang.reflect.Type;
4import java.util.List;
5
6class User {
7    int id;
8    String name;
9}
10
11Gson gson = new Gson();
12String json = """
13    [
14      {"id": 1, "name": "Ana"},
15      {"id": 2, "name": "Ben"}
16    ]
17    """;
18
19Type listType = new TypeToken<List<User>>() {}.getType();
20List<User> users = gson.fromJson(json, listType);
21
22System.out.println(users.size());

This is the most common fix because APIs often return lists even when the developer expects a single record.

Fix 2: Parse a Single Object When the JSON Is an Object

If the JSON really should be one object, then the payload itself must look like this:

{"id": 1, "name": "Ana"}

Then the original object parse is correct:

User user = gson.fromJson(json, User.class);

So the first debugging question is simple:

• is the payload an object
• or is it an array

Do not guess. Print the raw JSON and inspect the first non-whitespace character.

Watch for Wrapper Objects

Another common case is that the server returns an object containing an array:

1{
2  "users": [
3    {"id": 1, "name": "Ana"},
4    {"id": 2, "name": "Ben"}
5  ]
6}

In that case, the correct Java type is neither User nor List<User> directly. It is a wrapper class:

1import java.util.List;
2
3class UsersResponse {
4    List<User> users;
5}
6
7UsersResponse response = gson.fromJson(json, UsersResponse.class);
8System.out.println(response.users.size());

This is why reading the payload shape matters more than memorizing one fix.

Debug the Actual Payload, Not the API Docs Alone

Sometimes the docs say "returns a user", but the real endpoint returns a one-element array. Or the endpoint changes after a backend update. The safest way to debug is to log the raw response body before Gson touches it.

Once you know whether the JSON starts with:

• '[ for an array'
• '{" for an object'

the type mismatch usually becomes obvious.

Common Pitfalls

• Parsing an array response into a single object class.
• Forgetting to use TypeToken when deserializing generic collections such as List<User>.
• Assuming the payload is flat when the real response has a wrapper object around the array.
• Trusting an API description instead of inspecting the actual JSON returned at runtime.
• Trying to "fix" Gson configuration when the real issue is just a mismatched target type.

Summary

• The error means the JSON begins with an array, but your code asked Gson for an object.
• If the payload is an array, deserialize into a collection such as List<User>.
• If the payload is a wrapper object, create a wrapper class that matches it.
• Log and inspect the raw JSON before changing parsing code.
• Gson usually is not the problem here; the Java type and JSON shape simply do not match.