{"record":{"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/310ac341f2f92a454b229bf21f70d2d18b2b6db7/gson/src/main/java/com/google/gson/stream/JsonWriter.java#L488-L524","documentation":"Thrown by JsonWriter.name() (JsonWriter.java:504-507) when the current scope is not EMPTY_OBJECT or NONEMPTY_OBJECT, i.e. you are trying to write a property name outside an object. JSON names are only valid inside objects, so calling name() at the document root or inside an array is rejected.","triggerScenarios":"Calling name() before beginObject(); calling name() inside an array (where values, not names, are expected); calling name() at the top level of the document.","commonSituations":"Serializers that write field names without opening an object first; mis-ordered calls in hand-written serializers; conditional beginObject() that was skipped on a branch but name() still called.","solutions":["Call beginObject() before any name(); ensure the scope is an object when emitting names.","Move the beginObject() call to a place guaranteed to run before the first name().","Inside arrays, write values (or nested beginObject/beginArray), not names.","At the document root, write a single value or open one object/array before names."],"exampleFix":"// before\nwriter.name(\"a\").value(1); // throws: no object open\n\n// after\nwriter.beginObject();\nwriter.name(\"a\").value(1);\nwriter.endObject();","handlingStrategy":"validation","validationCode":"writer.beginObject();\ntry {\n  writer.name(\"a\").value(1);\n} finally {\n  writer.endObject();\n}","typeGuard":"// Track current scope in your serializer.\nboolean inObject = false;\nvoid ensureObject() throws IOException {\n  if (!inObject) { writer.beginObject(); inObject = true; }\n}","tryCatchPattern":"try {\n  writer.name(\"a\").value(1);\n} catch (IllegalStateException e) {\n  // missing beginObject; restructure rather than catch\n  throw e;\n}","preventionTips":["Call beginObject() before the first name().","At the document root or in arrays, write values not names.","Unit-test serializers against the full structural grammar."],"tags":["java","gson","jsonwriter","state-machine","serialization"],"backgroundTag":null,"analyzedSha":"310ac341f2f92a454b229bf21f70d2d18b2b6db7","analyzedAt":"2026-08-10T02:58:47.455Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}