{"id":"150114207e8209e7","repo":"google/gson","slug":"please-begin-an-object-before-writing-a-name","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/internal/bind/JsonTreeWriter.java","lineNumber":157,"sourceCode":"      stack.remove(stack.size() - 1);\n      return this;\n    }\n    throw new IllegalStateException();\n  }\n\n  @CanIgnoreReturnValue\n  @Override\n  public JsonWriter name(String name) throws IOException {\n    Objects.requireNonNull(name, \"name == null\");\n    if (stack.isEmpty() || pendingName != null) {\n      throw new IllegalStateException(\"Did not expect a name\");\n    }\n    JsonElement element = peek();\n    if (element instanceof JsonObject) {\n      pendingName = name;\n      return this;\n    }\n    throw new IllegalStateException(\"Please begin an object before writing a name.\");\n  }\n\n  @CanIgnoreReturnValue\n  @Override\n  public JsonWriter value(String value) throws IOException {\n    if (value == null) {\n      return nullValue();\n    }\n    put(new JsonPrimitive(value));\n    return this;\n  }\n\n  @CanIgnoreReturnValue\n  @Override\n  public JsonWriter value(boolean value) throws IOException {\n    put(new JsonPrimitive(value));\n    return this;\n  }","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/google/gson/blob/8b8628c65699bc4421696183c62ae0c1b9b281dc/gson/src/main/java/com/google/gson/internal/bind/JsonTreeWriter.java#L139-L175","documentation":"Thrown by JsonTreeWriter.name() when the stack is non-empty, pendingName is null, but the top of the stack is not a JsonObject (it's a JsonArray). name() is only valid inside an object; arrays contain values directly, not name/value pairs.","triggerScenarios":"Calling name() while the current open container is an array (top of stack is JsonArray). Typically a serializer that writes fields as name/value but the enclosing structure was opened as beginArray().","commonSituations":"Serializer that was written for an object output but is being driven inside an array context (e.g. a collection adapter); refactor that changed the root from object to array without removing name() calls; misconfigured custom adapter that emits name() unconditionally.","solutions":["Call beginObject() before name(); reserve name() for object contexts only.","If the enclosing structure must be an array, emit values directly with value()/beginObject() per element instead of name().","Restructure so the container kind matches the emit pattern: object -> name/value pairs, array -> bare values.","Guard name() with a check of the current container kind if your adapter is polymorphic."],"exampleFix":"// before: name() inside an array\nout.beginArray();\nout.name(\"x\").value(1); // throws: Please begin an object\nout.endArray();\n\n// after: either use an object, or emit bare values in the array\nout.beginArray();\nout.value(1);\nout.endArray();\n// or, if you want names:\nout.beginObject();\nout.name(\"x\").value(1);\nout.endObject();","handlingStrategy":"validation","validationCode":"// Ensure current container is an object before calling name()\nif (currentContainer != ContainerKind.OBJECT) throw new IllegalStateException(\"name() requires an object\");\nout.name(k);","typeGuard":null,"tryCatchPattern":"try {\n  out.name(k);\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Please begin an object\")) {\n    // open an object, or emit as a bare value if array was intended\n    out.value(v);\n  } else throw e;\n}","preventionTips":["Reserve name() for object contexts; arrays take bare values.","Keep container kind and emit pattern consistent within a serializer.","Test serializers under both object and array contexts if they are reused."],"tags":["json","streaming","writer-state","gson","container-mismatch"],"analyzedSha":"8b8628c65699bc4421696183c62ae0c1b9b281dc","analyzedAt":"2026-08-04T19:12:22.202Z","schemaVersion":2}