{"record":{"id":"8169fa8e4fd8765d","repo":"google/gson","slug":"array-must-have-size-1-but-has-size-size","errorCode":null,"errorMessage":"Array must have size 1, but has size ${size}","messagePattern":"Array must have size 1, but has size (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"gson/src/main/java/com/google/gson/JsonArray.java","lineNumber":240,"sourceCode":"\n  /**\n   * Returns the i-th element of the array.\n   *\n   * @param i the index of the element that is being sought.\n   * @return the element present at the i-th index.\n   * @throws IndexOutOfBoundsException if {@code i} is negative or greater than or equal to the\n   *     {@link #size()} of the array.\n   */\n  public JsonElement get(int i) {\n    return elements.get(i);\n  }\n\n  private JsonElement getAsSingleElement() {\n    int size = elements.size();\n    if (size == 1) {\n      return elements.get(0);\n    }\n    throw new IllegalStateException(\"Array must have size 1, but has size \" + size);\n  }\n\n  /**\n   * Convenience method to get this array as a {@link Number} if it contains a single element. This\n   * method calls {@link JsonElement#getAsNumber()} on the element, therefore any of the exceptions\n   * declared by that method can occur.\n   *\n   * @return this element as a number if it is single element array.\n   * @throws IllegalStateException if the array is empty or has more than one element.\n   */\n  @Override\n  public Number getAsNumber() {\n    return getAsSingleElement().getAsNumber();\n  }\n\n  /**\n   * Convenience method to get this array as a {@link String} if it contains a single element. This\n   * method calls {@link JsonElement#getAsString()} on the element, therefore any of the exceptions","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/google/gson/blob/310ac341f2f92a454b229bf21f70d2d18b2b6db7/gson/src/main/java/com/google/gson/JsonArray.java#L222-L258","documentation":"Thrown by JsonArray.getAsSingleElement() (an internal helper used by getAsNumber, getAsString, getAsBoolean, etc.) when the array does not contain exactly one element. These convenience coercion methods are only well-defined for a single-element array; an empty or multi-element array is ambiguous and raises an IllegalStateException naming the actual size.","triggerScenarios":"Calling getAsNumber()/getAsString()/getAsBoolean() (etc.) on a JsonArray with zero or with two+ elements; assuming a JSON array always wraps a single scalar; parsing an array-typed value through a single-value coercion path.","commonSituations":"API that sometimes returns an array of values where the consumer expects one; empty arrays for missing data; parsing config that uses arrays inconsistently; off-by-one index assumptions.","solutions":["Check jsonArray.size() == 1 before calling getAsNumber/getAsString/etc.","If multiple elements are valid, iterate the array and handle each, or pick an explicit index with get(i).","Treat size == 0 as the missing/null case explicitly.","Validate the JSON shape upstream (producer should send a scalar, not an array, when one value is expected)."],"exampleFix":"// before\nJsonArray a = jsonObj.getAsJsonArray(\"score\");\nString s = a.getAsString(); // size != 1 -> throws\n\n// after\nJsonArray a = jsonObj.getAsJsonArray(\"score\");\nString s = a.size() == 1 ? a.get(0).getAsString() : null;","handlingStrategy":"validation","validationCode":"// Guard single-element coercion on a JsonArray\nJsonArray a = element.getAsJsonArray();\nif (a.size() != 1) {\n  throw new IllegalStateException(\"Expected single-element array, got size \" + a.size());\n}\nString s = a.get(0).getAsString();","typeGuard":null,"tryCatchPattern":"try { String s = array.getAsString(); }\ncatch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Array must have size 1\")) {\n    // iterate, pick an index, or treat as missing\n  } else throw e;\n}","preventionTips":["Always check jsonArray.size() before single-value coercion methods.","Handle empty arrays explicitly as a missing/null case.","If multiple values are valid, iterate or index explicitly with get(i)."],"tags":["jsonarray","jsonelement","coercion","deserialization"],"backgroundTag":null,"analyzedSha":"310ac341f2f92a454b229bf21f70d2d18b2b6db7","analyzedAt":"2026-08-10T02:58:47.455Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}