{"id":"77d1fb067b652f9a","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/8b8628c65699bc4421696183c62ae0c1b9b281dc/gson/src/main/java/com/google/gson/JsonArray.java#L222-L258","documentation":"Thrown by JsonArray.getAsSingleElement, which backs every getAsXxx convenience accessor on JsonArray (getAsInt, getAsString, getAsDouble, getAsBoolean, etc.). It requires the array to contain exactly one element; empty arrays or arrays with two or more elements raise IllegalStateException.","triggerScenarios":"Calling jsonArray.getAsInt()/getAsString()/getAsDouble()/getAsBoolean()/getAsNumber()/getAsLong()/getAsBigDecimal()/... on a JsonArray whose size() is 0 or >= 2.","commonSituations":"An API field that is usually a single value but is modeled as a JSON array and occasionally returns [] or multiple entries; deserializing a list field into a scalar accessor; a server version change that started returning arrays where it used to return scalars.","solutions":["Check jsonArray.size() == 1 before calling any getAsXxx accessor.","For known-shape arrays, index explicitly with jsonArray.get(0).getAsInt() after a bounds check.","Handle empty arrays explicitly (default value or skip) and multi-element arrays by iterating.","If the field is genuinely a list, deserialize to List<T> rather than calling a scalar accessor on the JsonArray."],"exampleFix":"// before\nJsonArray arr = obj.getAsJsonArray(\"value\");\nint n = arr.getAsInt(); // throws if size != 1\n// after\nJsonArray arr = obj.getAsJsonArray(\"value\");\nif (arr.size() == 1) {\n  int n = arr.get(0).getAsInt();\n} else {\n  // handle empty / multi-element\n}","handlingStrategy":"validation","validationCode":"// Validate size before the scalar accessor\nJsonArray arr = obj.getAsJsonArray(\"v\");\nif (arr.size() != 1) {\n  throw new IllegalStateException(\"expected single-element array, got \" + arr.size());\n}\nint n = arr.getAsInt();","typeGuard":"boolean isSingleElement(JsonArray a) { return a != null && a.size() == 1; }","tryCatchPattern":"// Guard against variable server shapes\nJsonArray arr = obj.optJsonArray(\"v\");\nint n = (arr != null && arr.size() == 1) ? arr.get(0).getAsInt() : -1;","preventionTips":["Treat getAsXxx on JsonArray as a narrow contract: exactly one element.","Prefer List<T> deserialization for genuinely list-shaped data.","Add size() checks when an upstream API can return [] or [a,b]."],"tags":["gson","json-array","parsing","type-mismatch"],"analyzedSha":"8b8628c65699bc4421696183c62ae0c1b9b281dc","analyzedAt":"2026-08-04T19:12:22.202Z","schemaVersion":2}