{"id":"dc330d9fd2d008b2","repo":"google/gson","slug":"please-begin-an-object-before-writing-a-name-dc330d","errorCode":null,"errorMessage":"Please begin an object before writing a name.","messagePattern":"Please begin an object before writing a name\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"gson/src/main/java/com/google/gson/stream/JsonWriter.java","lineNumber":506,"sourceCode":"  private void replaceTop(int topOfStack) {\n    stack[stackSize - 1] = topOfStack;\n  }\n\n  /**\n   * Encodes the property name.\n   *\n   * @param name the name of the forthcoming value. May not be {@code null}.\n   * @return this writer.\n   */\n  @CanIgnoreReturnValue\n  public JsonWriter name(String name) throws IOException {\n    Objects.requireNonNull(name, \"name == null\");\n    if (deferredName != null) {\n      throw new IllegalStateException(\"Already wrote a name, expecting a value.\");\n    }\n    int context = peek();\n    if (context != EMPTY_OBJECT && context != NONEMPTY_OBJECT) {\n      throw new IllegalStateException(\"Please begin an object before writing a name.\");\n    }\n    deferredName = name;\n    return this;\n  }\n\n  private void writeDeferredName() throws IOException {\n    if (deferredName != null) {\n      beforeName();\n      string(deferredName);\n      deferredName = null;\n    }\n  }\n\n  /**\n   * Encodes {@code value}.\n   *\n   * @param value the literal string value, or null to encode a null literal.\n   * @return this writer.","sourceCodeStart":488,"sourceCodeEnd":524,"githubUrl":"https://github.com/google/gson/blob/8b8628c65699bc4421696183c62ae0c1b9b281dc/gson/src/main/java/com/google/gson/stream/JsonWriter.java#L488-L524","documentation":"Thrown by JsonWriter.name() when the current scope is neither EMPTY_OBJECT nor NONEMPTY_OBJECT. Property names are only valid inside a JSON object, so calling name() at the document root, inside an array, or before beginObject() is rejected to prevent malformed JSON.","triggerScenarios":"Calling writer.name(\"x\") before beginObject(), or inside an array (where elements, not names, are expected), or at the top level of the document.","commonSituations":"Forgetting to call beginObject() before writing fields; writing object-style code into an array context; porting serialization logic and losing the enclosing beginObject().","solutions":["Call writer.beginObject() before any name() call, and endObject() after the last value.","Verify the call ordering: name() is only valid between beginObject() and endObject().","When writing array elements, use value()/beginObject() per element rather than name().","Restructure so that object membership is established before names are written."],"exampleFix":"// before\nwriter.name(\"x\").value(1); // throws: no object started\nwriter.endObject();\n\n// after\nwriter.beginObject();\nwriter.name(\"x\").value(1);\nwriter.endObject();","handlingStrategy":"validation","validationCode":"// Ensure beginObject() precedes name()\nwriter.beginObject();\ntry {\n  writer.name(\"x\").value(1);\n} finally {\n  writer.endObject();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always call beginObject() before the first name() and endObject() after the last value.","Inside arrays, use value()/beginObject() per element, not name().","Establish object scope in a single place to avoid forgetting beginObject().","Prefer Gson's POJO/tree serialization for nested structures."],"tags":["gson","jsonwriter","state-machine","api-misuse","nesting"],"analyzedSha":"8b8628c65699bc4421696183c62ae0c1b9b281dc","analyzedAt":"2026-08-04T19:12:22.202Z","schemaVersion":2}