TheAlgorithms/Java · error · IllegalArgumentException

Cannot enqueue null item.

Error message

Cannot enqueue null item.

What it means

Thrown by ThreadSafeQueue.enqueue(T) as an IllegalArgumentException when item == null. The null check runs before acquiring the lock, so the exception is raised immediately (synchronously) rather than after blocking. The queue forbids nulls to avoid ambiguity with the internal buffer slots and to keep dequeue()'s return unambiguous.

Source

Thrown at src/main/java/com/thealgorithms/datastructures/queues/ThreadSafeQueue.java:52

        this.capacity = capacity;
        this.buffer = new Object[capacity];
        this.head = 0;
        this.tail = 0;
        this.count = 0;
        this.lock = new ReentrantLock();
        this.notFull = lock.newCondition();
        this.notEmpty = lock.newCondition();
    }

    /**
     * @brief Adds an element to the tail of the queue, blocking if full
     * @param item the element to add
     * @throws InterruptedException if the thread is interrupted while waiting
     * @throws IllegalArgumentException if the item is null
     */
    public void enqueue(T item) throws InterruptedException {
        if (item == null) {
            throw new IllegalArgumentException("Cannot enqueue null item.");
        }

        lock.lock();
        try {
            while (count == capacity) {
                notFull.await();
            }
            buffer[tail] = item;
            tail = (tail + 1) % capacity;
            count++;
            notEmpty.signalAll();
        } finally {
            lock.unlock();
        }
    }

    /**
     * @brief Removes and returns the element at the head of the queue, blocking if empty

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Null-check before enqueue: if (item != null) queue.enqueue(item).
2. Filter nulls at the source (Stream.filter(Objects::nonNull)) so they never reach the queue.
3. Replace missing values with a non-null sentinel/empty representation.

Example fix

// before
queue.enqueue(source.poll()); // poll may return null

// after
T item = source.poll();
if (item != null) {
    queue.enqueue(item);
}

if (item != null) {
    queue.enqueue(item);
}

java.util.Objects.nonNull(item)

null

When it happens

Trigger: Passing a literal null, or an expression that evaluates to null (uninitialized field, Map.get on a missing key, Optional.orElse(null)), to enqueue(). The throw happens before any lock/wait, so it occurs even when the queue is empty and would otherwise accept an element.

Common situations: Producer feeding the queue from a nullable source without filtering; null fields from JSON/DB deserialization; race-free but value-uninitialized producer variables; refactors that dropped an assignment upstream.

Related errors

• Cannot enqueue null data
• Capacity must be greater than zero.
• Queue capacity must be greater than 0
• Cannot insert null element
• Cannot add null element to the list

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