{"record":{"id":"b1069c2ac48de5da","repo":"TheAlgorithms/Java","slug":"cannot-enqueue-null-item","errorCode":null,"errorMessage":"Cannot enqueue null item.","messagePattern":"Cannot enqueue null item\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/thealgorithms/datastructures/queues/ThreadSafeQueue.java","lineNumber":52,"sourceCode":"        this.capacity = capacity;\n        this.buffer = new Object[capacity];\n        this.head = 0;\n        this.tail = 0;\n        this.count = 0;\n        this.lock = new ReentrantLock();\n        this.notFull = lock.newCondition();\n        this.notEmpty = lock.newCondition();\n    }\n\n    /**\n     * @brief Adds an element to the tail of the queue, blocking if full\n     * @param item the element to add\n     * @throws InterruptedException if the thread is interrupted while waiting\n     * @throws IllegalArgumentException if the item is null\n     */\n    public void enqueue(T item) throws InterruptedException {\n        if (item == null) {\n            throw new IllegalArgumentException(\"Cannot enqueue null item.\");\n        }\n\n        lock.lock();\n        try {\n            while (count == capacity) {\n                notFull.await();\n            }\n            buffer[tail] = item;\n            tail = (tail + 1) % capacity;\n            count++;\n            notEmpty.signalAll();\n        } finally {\n            lock.unlock();\n        }\n    }\n\n    /**\n     * @brief Removes and returns the element at the head of the queue, blocking if empty","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/TheAlgorithms/Java/blob/fdfb9a395b310167a66bd29e311e36e0e3e9b964/src/main/java/com/thealgorithms/datastructures/queues/ThreadSafeQueue.java#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Null-check before enqueue: if (item != null) queue.enqueue(item).","Filter nulls at the source (Stream.filter(Objects::nonNull)) so they never reach the queue.","Replace missing values with a non-null sentinel/empty representation."],"exampleFix":"// before\nqueue.enqueue(source.poll()); // poll may return null\n\n// after\nT item = source.poll();\nif (item != null) {\n    queue.enqueue(item);\n}","handlingStrategy":"validation","validationCode":"if (item != null) {\n    queue.enqueue(item);\n}","typeGuard":"java.util.Objects.nonNull(item)","tryCatchPattern":"null","preventionTips":["Null-check before enqueue; the check happens pre-lock so it throws synchronously.","Filter nulls at the producer source so they never reach the queue.","Avoid Optional.orElse(null) feeding enqueue directly."],"tags":["queue","data-structure","concurrency","null-check","input-validation","java"],"backgroundTag":null,"analyzedSha":"fdfb9a395b310167a66bd29e311e36e0e3e9b964","analyzedAt":"2026-08-13T23:36:13.315Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}