alibaba/nacos · warning · IllegalArgumentException

iterable cannot be null.

Error message

iterable cannot be null.

What it means

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.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/utils/CollectionUtils.java:309

        if (elements == null) {
            throw new IllegalArgumentException(
                "Expected an array of elements (or empty array) but received a null.");
        } else {
            return new LinkedHashSet<>(Arrays.asList(elements));
        }
    }
    
    /**
     * return the first element, if the iterator contains multiple elements, will throw {@code
     * IllegalArgumentException}.
     *
     * @throws NoSuchElementException   if the iterator is empty
     * @throws IllegalArgumentException if the iterator contains multiple elements. The state of the iterator is
     *                                  unspecified.
     */
    public static <T> T getOnlyElement(Iterable<T> iterable) {
        if (iterable == null) {
            throw new IllegalArgumentException("iterable cannot be null.");
        }
        Iterator<T> iterator = iterable.iterator();
        T first = iterator.next();
        if (!iterator.hasNext()) {
            return first;
        }
        throw new IllegalArgumentException(buildExceptionMessage(iterator, first));
    }
    
    private static <T> String buildExceptionMessage(Iterator<T> iterator, T first) {
        StringBuilder msg = new StringBuilder();
        msg.append("expected one element but was: <");
        msg.append(first);
        for (int i = 0; i < 4 && iterator.hasNext(); i++) {
            msg.append(", ");
            msg.append(iterator.next());
        }
        if (iterator.hasNext()) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Null-check before calling, or normalize upstream returns to empty collections.
2. If you want null-safety, wrap: iterable != null ? getOnlyElement(iterable) : null (or throw a domain-specific exception).
3. Use Optional.ofNullable(iterable).map(CollectionUtils::getOnlyElement) when appropriate.

Example fix

// before
T only = CollectionUtils.getOnlyElement(maybeNullIterable);

// after
T only = maybeNullIterable == null ? null : CollectionUtils.getOnlyElement(maybeNullIterable);

if (iterable == null) {
    throw new IllegalArgumentException("iterable required"); // or return null/default
}
T only = CollectionUtils.getOnlyElement(iterable);

When it happens

Trigger: Calling getOnlyElement(null), or passing a field/method result that is null without prior validation.

Common situations: A collection-returning API that can return null (instead of empty) is fed directly into getOnlyElement; refactoring that made an upstream return nullable.

Related errors

• Unsupported object type: null
• Unsupported object type: {}
• Expected an array of elements (or empty array) but received
• expected one element but was: <{}>
• Agent replacement must not be null

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/93ee1befb3ff2887. Report an issue: GitHub.