{"record":{"id":"1618a5f16d8d0ac5","repo":"TheAlgorithms/Java","slug":"queue-is-empty-cannot-peek-front","errorCode":null,"errorMessage":"Queue is empty, cannot peek front","messagePattern":"Queue is empty, cannot peek front","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/thealgorithms/datastructures/queues/Queue.java","lineNumber":87,"sourceCode":"            throw new IllegalStateException(\"Queue is empty, cannot remove element\");\n        }\n        T removedElement = (T) queueArray[front];\n        queueArray[front] = null; // Optional: Clear the reference for garbage collection\n        front = (front + 1) % maxSize;\n        nItems--;\n        return removedElement;\n    }\n\n    /**\n     * Checks the element at the front of the queue without removing it.\n     *\n     * @return Element at the front of the queue.\n     * @throws IllegalStateException if the queue is empty.\n     */\n    @SuppressWarnings(\"unchecked\")\n    public T peekFront() {\n        if (isEmpty()) {\n            throw new IllegalStateException(\"Queue is empty, cannot peek front\");\n        }\n        return (T) queueArray[front];\n    }\n\n    /**\n     * Checks the element at the rear of the queue without removing it.\n     *\n     * @return Element at the rear of the queue.\n     * @throws IllegalStateException if the queue is empty.\n     */\n    @SuppressWarnings(\"unchecked\")\n    public T peekRear() {\n        if (isEmpty()) {\n            throw new IllegalStateException(\"Queue is empty, cannot peek rear\");\n        }\n        return (T) queueArray[rear];\n    }\n","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/TheAlgorithms/Java/blob/fdfb9a395b310167a66bd29e311e36e0e3e9b964/src/main/java/com/thealgorithms/datastructures/queues/Queue.java#L69-L105","documentation":"Thrown by Queue.peekFront() as an IllegalStateException when isEmpty(). The method returns queueArray[front] without removing it; with nItems == 0 there is no valid front to read. Read-only underflow guard.","triggerScenarios":"Calling peekFront() on a newly constructed Queue, or after every inserted element has been removed(). peekFront never changes occupancy, so an empty queue always throws.","commonSituations":"Inspecting the next element for routing/throttling before producers have inserted; startup health checks that peek before seeding; tests asserting front state without data.","solutions":["Check isEmpty() before peekFront() and return null/Optional in the empty case.","Seed the queue with at least one insert() before the first peekFront().","Catch IllegalStateException when emptiness is a legitimate control-flow path."],"exampleFix":"// before\nT head = queue.peekFront(); // throws when empty\n\n// after\nT head = queue.isEmpty() ? null : queue.peekFront();","handlingStrategy":"validation","validationCode":"T head = queue.isEmpty() ? null : queue.peekFront();","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Always isEmpty()-guard peekFront.","Return Optional<T> from a wrapper to encode emptiness in the type.","Seed the queue before any startup peek path."],"tags":["queue","data-structure","underflow","empty-state","java"],"backgroundTag":null,"analyzedSha":"fdfb9a395b310167a66bd29e311e36e0e3e9b964","analyzedAt":"2026-08-13T23:36:13.315Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}