{"record":{"id":"93ee1befb3ff2887","repo":"alibaba/nacos","slug":"iterable-cannot-be-null","errorCode":null,"errorMessage":"iterable cannot be null.","messagePattern":"iterable cannot be null\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"common/src/main/java/com/alibaba/nacos/common/utils/CollectionUtils.java","lineNumber":309,"sourceCode":"        if (elements == null) {\n            throw new IllegalArgumentException(\n                \"Expected an array of elements (or empty array) but received a null.\");\n        } else {\n            return new LinkedHashSet<>(Arrays.asList(elements));\n        }\n    }\n    \n    /**\n     * return the first element, if the iterator contains multiple elements, will throw {@code\n     * IllegalArgumentException}.\n     *\n     * @throws NoSuchElementException   if the iterator is empty\n     * @throws IllegalArgumentException if the iterator contains multiple elements. The state of the iterator is\n     *                                  unspecified.\n     */\n    public static <T> T getOnlyElement(Iterable<T> iterable) {\n        if (iterable == null) {\n            throw new IllegalArgumentException(\"iterable cannot be null.\");\n        }\n        Iterator<T> iterator = iterable.iterator();\n        T first = iterator.next();\n        if (!iterator.hasNext()) {\n            return first;\n        }\n        throw new IllegalArgumentException(buildExceptionMessage(iterator, first));\n    }\n    \n    private static <T> String buildExceptionMessage(Iterator<T> iterator, T first) {\n        StringBuilder msg = new StringBuilder();\n        msg.append(\"expected one element but was: <\");\n        msg.append(first);\n        for (int i = 0; i < 4 && iterator.hasNext(); i++) {\n            msg.append(\", \");\n            msg.append(iterator.next());\n        }\n        if (iterator.hasNext()) {","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/common/src/main/java/com/alibaba/nacos/common/utils/CollectionUtils.java#L291-L327","documentation":"Thrown by CollectionUtils.getOnlyElement(Iterable) when the iterable argument is null. getOnlyElement is a strict helper: it expects exactly one element and treats a null iterable as a contract violation rather than an empty case.","triggerScenarios":"Calling getOnlyElement(null), or passing a field/method result that is null without prior validation.","commonSituations":"A collection-returning API that can return null (instead of empty) is fed directly into getOnlyElement; refactoring that made an upstream return nullable.","solutions":["Null-check before calling, or normalize upstream returns to empty collections.","If you want null-safety, wrap: iterable != null ? getOnlyElement(iterable) : null (or throw a domain-specific exception).","Use Optional.ofNullable(iterable).map(CollectionUtils::getOnlyElement) when appropriate."],"exampleFix":"// before\nT only = CollectionUtils.getOnlyElement(maybeNullIterable);\n\n// after\nT only = maybeNullIterable == null ? null : CollectionUtils.getOnlyElement(maybeNullIterable);","handlingStrategy":"validation","validationCode":"if (iterable == null) {\n    throw new IllegalArgumentException(\"iterable required\"); // or return null/default\n}\nT only = CollectionUtils.getOnlyElement(iterable);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Null-check before getOnlyElement.","Normalize upstream returns to empty collections rather than null."],"tags":["collections","null-check","validation","utility"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}