TheAlgorithms/Java · error · IllegalArgumentException

Null items are not allowed

Error message

Null items are not allowed

What it means

Thrown by CircularBuffer.put(Item) when the supplied item is null. The buffer treats null as a non-value because null is indistinguishable from an uninitialized slot and would corrupt FIFO semantics (a null returned by get() already signals emptiness). The guard runs before any pointer mutation, so a rejected put leaves the buffer state untouched.

Source

Thrown at src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java:82

            return null;
        }

        Item item = buffer[getPointer.getAndIncrement()];
        size.decrementAndGet();
        return item;
    }

    /**
     * Adds an item to the end of the buffer (FIFO).
     * If the buffer is full, this operation will overwrite the oldest data.
     *
     * @param item The item to be added.
     * @throws IllegalArgumentException if the item is null.
     * @return {@code true} if the item was successfully added, {@code false} if the buffer was full and the item overwrote existing data.
     */
    public boolean put(Item item) {
        if (item == null) {
            throw new IllegalArgumentException("Null items are not allowed");
        }

        boolean wasEmpty = isEmpty();
        if (isFull()) {
            getPointer.getAndIncrement(); // Move get pointer to discard oldest item
        } else {
            size.incrementAndGet();
        }

        buffer[putPointer.getAndIncrement()] = item;
        return wasEmpty;
    }

    /**
     * The {@code CircularPointer} class is a helper class used to track the current index (pointer)
     * in the circular buffer.
     * The max value represents the capacity of the buffer.
     * The `CircularPointer` class ensures that the pointer automatically wraps around to 0

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Filter or replace nulls at the producer before calling put(): if (item != null) buffer.put(item);
2. Use Optional or a sentinel value to represent 'no data' instead of null.
3. If null must be representable, wrap items in a small holder object.

Example fix

// before
buffer.put(queue.poll());
// after
Item next = queue.poll();
if (next != null) buffer.put(next);

if (item == null) {
    // skip, log, or substitute a sentinel
    return;
}
buffer.put(item);

static <Item> boolean isAddable(Item item) {
    return item != null;
}

When it happens

Trigger: Calling circularBuffer.put(null) directly; passing a value sourced from a Map.get() that may return null; feeding a producer whose next() can yield null into the buffer without filtering.

Common situations: Producer/consumer pipelines where the upstream source has optional elements; deserialization that maps missing fields to null; refactoring a buffer from a primitive array to a generic type and forgetting null was newly allowed.

Related errors

• Buffer size must be positive
• Key must not be null
• Key and value must not be null
• Key cannot be null
• Listener must not be null

AI-assisted analysis of TheAlgorithms/Java@fdfb9a395b (2026-08-13). Data as JSON: /api/errors/088df96e5eb03f54. Report an issue: GitHub.