1. Overview
When working with JSON in Java, one of the most common runtime errors developers face is org.json.JSONException: JSONObject text must begin with ‘{‘ at character 0.
At first glance, this looks cryptic. But once we understand what’s happening under the hood, it becomes easy to fix.
In this tutorial, we’ll explore why this exception occurs, what it means, and how to resolve it with clear examples.
2. Understanding the Error
The JSONException typically occurs when using the org.json library from the org.json package, also known as JSON-java.
When we create a JSONObject from a string, the constructor expects that string to represent a valid JSON object:
JSONObject json = new JSONObject("{\"name\":\"Baeldung\"}");
This works fine because the string starts with { and ends with }, which is the proper JSON object format.
However, if we pass something that isn’t a valid JSON object, such as:
JSONObject json = new JSONObject("[1, 2, 3]");
We’ll get this error, org.json.JSONException: JSONObject text must begin with ‘{‘ at 1 [character 2 line 1].
The core of the problem lies in the type of JSON data we’re trying to parse.
There are two major types of JSON structures:
If our input string starts with:
- { – It represents a JSON Object
- [ – It represents a JSON Array
So, if our input starts with [, but we try to parse it as a JSONObject, we’ll see this exact error.
3. Common Scenarios That Trigger the Error
Let’s look at a few real-world cases where this exception often appears.
3.1. Parsing a JSON Array as a JSONObject
This is the most common scenario that triggers the error. We might receive a JSON array from an API but mistakenly try to parse it as a JSONObject:
String jsonResponse = "[{\"id\":1, \"name\":\"Alice\"}, {\"id\":2, \"name\":\"Bob\"}]";
JSONObject json = new JSONObject(jsonResponse);
The code above fails because the JSON string starts with [, indicating it’s an array, not an object.
To fix this, we should use the JSONArray class instead, which correctly represents a list of JSON objects:
JSONArray jsonArray = new JSONArray(jsonResponse);
System.out.println(jsonArray.getJSONObject(0).getString("name"));
Now, the code executes without error, and we can easily access each element within the array using the getJSONObject(index) method.
3.2. Receiving Invalid JSON from an API
Sometimes, APIs return malformed responses (such as HTML or plain text) instead of JSON. For example:
String response = "<html>Server Error</html>";
JSONObject json = new JSONObject(response);
To fix this, always validate the response before parsing:
if (response.trim().startsWith("{")) {
JSONObject json = new JSONObject(response);
} else {
System.out.println("Invalid JSON response: " + response);
}
This ensures we only parse valid JSON.
3.3. Empty or Null String
Sometimes, the JSON source might be empty or return null due to a failed API call or an uninitialized variable.
If we try to parse such an input directly, the JSONObject constructor will throw a JSONException:
String json = "";
JSONObject obj = new JSONObject(json);
The above code fails because an empty string is not valid JSON, it doesn’t begin with { or [.
To handle this safely, always check for null or empty strings before attempting to parse:
if (json != null && !json.trim().isEmpty()) {
JSONObject obj = new JSONObject(json);
} else {
System.out.println("Empty or null JSON string");
}
This simple validation ensures our code won’t break if the response is missing or empty, making our JSON parsing logic more reliable and robust.
4. Conclusion
In this article, we saw that working with JSON in Java becomes effortless once we understand how the org.json library interprets data.
A single misplaced [ or { can cause confusion, but with careful validation, logging, and consistent parsing logic, we can handle JSON like a pro.
As always, the code presented in this article is available over on GitHub.
