What causes "Did not consume the entire document." in google/gson?

Use JsonReader.parseReader only on inputs known to contain one top-level value; strip trailing content.

google/gson · error · JsonSyntaxException

Did not consume the entire document.

Error message

Did not consume the entire document.

What it means

JsonParser.parseReader(Reader) parses exactly one top-level JSON value and then verifies the reader is exhausted; if peek() does not return END_DOCUMENT it throws JsonSyntaxException with this message. It guards against concatenated or trailing garbage after the first JSON value, which the lenient parser would otherwise silently accept.

Source

Thrown at gson/src/main/java/com/google/gson/JsonParser.java:112

  /**
   * Parses the complete JSON string provided by the reader into a parse tree. An exception is
   * thrown if the JSON string has multiple top-level JSON elements, or if there is trailing data.
   *
   * <p>The JSON data is parsed in {@linkplain JsonReader#setStrictness(Strictness) lenient mode}.
   *
   * @param reader JSON text
   * @return a parse tree of {@link JsonElement}s corresponding to the specified JSON
   * @throws JsonParseException if there is an IOException or if the specified text is not valid
   *     JSON
   * @since 2.8.6
   */
  public static JsonElement parseReader(Reader reader) throws JsonIOException, JsonSyntaxException {
    try {
      JsonReader jsonReader = new JsonReader(reader);
      JsonElement element = parseReader(jsonReader);
      if (!element.isJsonNull() && jsonReader.peek() != JsonToken.END_DOCUMENT) {
        throw new JsonSyntaxException("Did not consume the entire document.");
      }
      return element;
    } catch (MalformedJsonException | NumberFormatException e) {
      throw new JsonSyntaxException(e);
    } catch (IOException e) {
      throw new JsonIOException(e);
    }
  }

  /**
   * Returns the next value from the JSON stream as a parse tree. Unlike the other {@code parse}
   * methods, no exception is thrown if the JSON data has multiple top-level JSON elements, or if
   * there is trailing data.
   *
   * <p>If the {@linkplain JsonReader#getStrictness() strictness of the reader} is {@link
   * Strictness#STRICT}, that strictness will be used for parsing. Otherwise the strictness will be
   * temporarily changed to {@link Strictness#LENIENT} and will be restored once this method
   * returns.

View on GitHub (pinned to 8b8628c656)

Solutions

Use JsonReader.parseReader only on inputs known to contain one top-level value; strip trailing content.
For multiple top-level values, use JsonStreamParser or read repeatedly with JsonReader in a loop.
Validate/trim the string and check for stray characters after the closing token.
Switch to gson.fromJson(json, type) which enforces single-document semantics with clearer errors.

Example fix

// before
JsonElement e = JsonParser.parseReader(new StringReader(concatenated));

// after (multiple docs)
JsonStreamParser it = new JsonStreamParser(new StringReader(concatenated));
while (it.hasNext()) {
  JsonElement e = it.next();
  // ...
}

Defensive patterns

Strategy: validation

Validate before calling

String trimmed = json.trim();
// verify only one top-level value before parseReader
try (JsonReader r = new JsonReader(new StringReader(trimmed))) {
  r.setStrictness(Strictness.STRICT);
  // single parse + END_DOCUMENT expectation enforced by parseReader
}

Type guard

boolean isSingleDocument(String json) {
  JsonReader r = new JsonReader(new StringReader(json));
  try {
    r.skipValue();
    return r.peek() == JsonToken.END_DOCUMENT;
  } catch (Exception ex) { return false; }
  finally { try { r.close(); } catch (IOException ignored) {} }
}

Try / catch

try {
  JsonElement e = JsonParser.parseReader(reader);
} catch (JsonSyntaxException ex) {
  if (ex.getMessage().contains("Did not consume")) {
    // switch to JsonStreamParser for multi-doc input
  } else throw ex;
}

Prevention

Use JsonStreamParser when input may contain multiple top-level values.
Strip trailing whitespace/comments before parsing.
Validate test fixtures contain exactly one JSON value.

When it happens

Trigger: Calling JsonParser.parseReader(new StringReader("{}{}")) or any input with two top-level values, trailing commas/content, or whitespace-separated documents; feeding a stream that contains a value followed by leftover log text.

Common situations: Reading NDJSON/log lines as a single document; concatenated API responses in one buffer; copy-paste artifacts (extra brace) in test fixtures; a Reader that was already partially consumed.

Related errors

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/2706ed57eb8d436a.json. Report an issue: GitHub.