{"record":{"id":"bd0fa4c2110ecb76","repo":"google/gson","slug":"incomplete-document","errorCode":null,"errorMessage":"Incomplete document","messagePattern":"Incomplete document","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"gson/src/main/java/com/google/gson/internal/bind/JsonTreeWriter.java","lineNumber":250,"sourceCode":"  @CanIgnoreReturnValue\n  @Override\n  public JsonWriter nullValue() throws IOException {\n    put(JsonNull.INSTANCE);\n    return this;\n  }\n\n  @Override\n  public JsonWriter jsonValue(String value) throws IOException {\n    throw new UnsupportedOperationException();\n  }\n\n  @Override\n  public void flush() throws IOException {}\n\n  @Override\n  public void close() throws IOException {\n    if (!stack.isEmpty()) {\n      throw new IOException(\"Incomplete document\");\n    }\n    stack.add(SENTINEL_CLOSED);\n  }\n}\n","sourceCodeStart":232,"sourceCodeEnd":255,"githubUrl":"https://github.com/google/gson/blob/310ac341f2f92a454b229bf21f70d2d18b2b6db7/gson/src/main/java/com/google/gson/internal/bind/JsonTreeWriter.java#L232-L255","documentation":"JsonTreeWriter.close() requires a complete, balanced document. If any container is still open (stack non-empty) when close() is called, it throws IOException(\"Incomplete document\"). This catches unterminated beginObject()/beginArray() calls at close time, including when JsonWriter is used in a try-with-resources block that exits before all containers are closed.","triggerScenarios":"Calling close() (often via try-with-resources on JsonWriter) before all beginObject/beginArray calls have matching end calls; an exception mid-serialization that unwinds to the implicit close.","commonSituations":"try-with-resources on JsonWriter where the body throws or returns early; mismatched begin/end; streaming serialization that aborts partway through.","solutions":["Match every beginObject/beginArray with its end call before closing","Use try-finally to ensure end calls run even when an exception is thrown","Avoid try-with-resources on JsonWriter for partial writes; manage close() manually after confirming balance"],"exampleFix":"// before - try-with-resources closes with an open container\ntry (JsonWriter w = jsonWriter) {\n  w.beginObject();\n  w.name(\"a\").value(1);\n  // returns, close() throws: Incomplete document\n}\n\n// after - end the container before close\ntry (JsonWriter w = jsonWriter) {\n  w.beginObject();\n  w.name(\"a\").value(1);\n  w.endObject();\n}","handlingStrategy":"validation","validationCode":"// Ensure all containers are closed before close()\nif (openContainers != 0) {\n    throw new IllegalStateException(\"Cannot close: \" + openContainers + \" open containers\");\n}\nwriter.close();","typeGuard":null,"tryCatchPattern":"try {\n  writer.close();\n} catch (IOException e) {\n  // 'Incomplete document': an open container remains; end it then close again\n}","preventionTips":["Match every begin with an end before close()","Use try-finally to guarantee end calls on exception paths","Avoid try-with-resources on JsonWriter for partial writes; close manually after confirming balance"],"tags":["json","serialization","resource-management","state-machine"],"backgroundTag":null,"analyzedSha":"310ac341f2f92a454b229bf21f70d2d18b2b6db7","analyzedAt":"2026-08-10T02:58:47.455Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}