Fix Kotlin JSON Parsing Error with Gson or Moshi

Are you struggling with a Kotlin JSON parsing error while using Gson or Moshi in your Android project? This is a common issue, especially when your JSON structure doesn’t perfectly align with your data models or when null values and incorrect annotations cause parsing to fail.

In this tutorial, we’ll explore how to fix JSON parsing errors using both Gson and Moshi, two of the most popular libraries for JSON deserialization in Kotlin. You’ll also learn about the typical causes such as missing @SerializedName annotations, incorrect data types, or ignoring unknown JSON fields.

Example using Gson:

// Data class with SerializedName annotation
data class User(
    @SerializedName("id") val id: Int,
    @SerializedName("name") val name: String
)

// Gson parsing
val json = """{"id": 1, "name": "John"}"""
val user = Gson().fromJson(json, User::class.java)

Common Error:
java.lang.IllegalStateException: Expected BEGIN_OBJECT but was STRING

Fix: Ensure the JSON is correctly formatted and matches your data class. Wrap objects properly and check types.

Example using Moshi:

// Moshi model class
@JsonClass(generateAdapter = true)
data class User(
    val id: Int,
    val name: String
)

// Moshi parsing
val moshi = Moshi.Builder().build()
val adapter = moshi.adapter(User::class.java)
val user = adapter.fromJson("""{"id": 2, "name": "Alice"}""")

Common Error:
Expected BEGIN_OBJECT but was STRING at path $

Fix: Double-check the incoming JSON structure. Use @JsonClass(generateAdapter = true) and ensure Moshi dependency is correctly implemented.

Bonus Tip:

Always use JSON Schema Validator to test your JSON format before parsing in Kotlin.

If you’re receiving errors like Expected BEGIN_OBJECT but was STRING, or encountering null pointer exceptions, make sure your Kotlin data classes match the exact JSON structure, including handling optional or missing fields with nullable types (?) or default values.