What causes "UnsupportedOperationException" in apache/pulsar?

Use forEach or toList to traverse elements

apache/pulsar · warning · UnsupportedOperationException

UnsupportedOperationException

Error message

UnsupportedOperationException

What it means

Deliberate UnsupportedOperationException from GrowableArrayBlockingQueue.iterator: this custom lock-free queue does not support snapshot iteration (its internal ring buffer mutates concurrently), so any caller attempting to iterate (e.g. via streams or for-each) is rejected; use forEach or toList instead.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/util/collections/GrowableArrayBlockingQueue.java:366

        }

        if (tailIndex > 0) {
            data[tailIndex - 1] = null;
        } else {
            data[data.length - 1] = null;
        }

        SIZE_UPDATER.decrementAndGet(this);
    }

    @Override
    public int size() {
        return SIZE_UPDATER.get(this);
    }

    @Override
    public Iterator<T> iterator() {
        throw new UnsupportedOperationException();
    }

    public List<T> toList() {
        List<T> list = new ArrayList<>(size());
        forEach(list::add);
        return list;
    }

    @Override
    public void forEach(Consumer<? super T> action) {
        long stamp = tailLock.writeLock();
        headLock.lock();

        try {
            int headIndex = this.headIndex.value;
            int size = this.size;

            for (int i = 0; i < size; i++) {

View on GitHub (pinned to 820761864e)

Solutions

Use forEach or toList to traverse elements

Example fix

// before
for (T item : queue) { process(item); } // throws
// after
for (T item : queue.toList()) { process(item); }

Defensive patterns

Strategy: type-guard

Try / catch

try {
    for (T item : queue) { ... }
} catch (UnsupportedOperationException e) {
    queue.forEach(this::process); // supported alternative
}

Prevention

Never use GrowableArrayBlockingQueue in for-each; use forEach or toList()
Check the class Javadoc before using Collection-derived methods
Pass consumers a List (toList()) instead of the queue when iteration is needed

When it happens

Trigger: Using the queue in a for-each loop, passing it to code that calls iterator() (e.g. streams, collection copying, toString-based logging).

Common situations: Code that assumes every Collection is iterable (for (T t : queue) {...}) or library helpers that snapshot via iterator.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/cd695fd008d7e538. Report an issue: GitHub.