[Feature] Improve logging for error messages

Signed-off-by: Elizabeth Thomas <[email protected]>

Author: elizabetht

README.md

@@ -92,7 +92,7 @@ Find the full list of supported models [here](https://docs.vllm.ai/en/latest/mod
 Install vLLM with `pip` or [from source](https://docs.vllm.ai/en/latest/getting_started/installation/gpu/index.html#build-wheel-from-source):
 
 ```bash
-pip install vllm
+uv pip install vllm
 ```
 
 Visit our [documentation](https://docs.vllm.ai/en/latest/) to learn more.

tests/v1/engine/test_initialization_errors.py

@@ -651,17 +651,30 @@ def check_enough_kv_cache_memory(vllm_config: VllmConfig,
         available_memory: Memory available for KV cache in bytes.
 
     Raises:
-        ValueError: If there is not enough memory available for the KV cache.
+        InsufficientKVCacheMemoryError: If there is not enough memory available for the KV cache.
     """
+    from vllm.v1.engine.initialization_errors import (
+        InsufficientKVCacheMemoryError, get_memory_suggestions
+    )
 
     # No need to check for available memory if the kv_cache_spec is empty
     if not kv_cache_spec:
         return
 
     if available_memory <= 0:
-        raise ValueError("No available memory for the cache blocks. "
-                         "Try increasing `gpu_memory_utilization` when "
-                         "initializing the engine.")
+        suggestions = get_memory_suggestions(
+            required_memory=1024**3,  # 1 GiB as minimum
+            available_memory=available_memory,
+            current_gpu_utilization=vllm_config.cache_config.gpu_memory_utilization,
+            max_model_len=vllm_config.model_config.max_model_len,
+            is_kv_cache=True
+        )
+        raise InsufficientKVCacheMemoryError(
+            required_kv_memory=1024**3,  # 1 GiB as minimum
+            available_kv_memory=available_memory,
+            max_model_len=vllm_config.model_config.max_model_len,
+            suggestions=suggestions
+        )
 
     max_model_len = vllm_config.model_config.max_model_len
     needed_memory = max_memory_usage_bytes(vllm_config, kv_cache_spec.values())
@@ -670,20 +683,26 @@ def check_enough_kv_cache_memory(vllm_config: VllmConfig,
         # Estimate the maximum model length that can fit in the available memory
         estimated_max_len = estimate_max_model_len(vllm_config, kv_cache_spec,
                                                    available_memory)
-        estimated_msg = ""
+        
+        suggestions = get_memory_suggestions(
+            required_memory=needed_memory,
+            available_memory=available_memory,
+            current_gpu_utilization=vllm_config.cache_config.gpu_memory_utilization,
+            max_model_len=max_model_len,
+            is_kv_cache=True
+        )
+        
+        # Add model-specific suggestions
         if estimated_max_len > 0:
-            estimated_msg = (
-                "Based on the available memory, "
-                f"the estimated maximum model length is {estimated_max_len}.")
-
-        raise ValueError(
-            f"To serve at least one request with the models's max seq len "
-            f"({max_model_len}), ({needed_memory/GiB_bytes:.2f} GiB KV "
-            f"cache is needed, which is larger than the available KV cache "
-            f"memory ({available_memory/GiB_bytes:.2f} GiB). "
-            f"{estimated_msg} "
-            f"Try increasing `gpu_memory_utilization` or decreasing "
-            f"`max_model_len` when initializing the engine.")
+            suggestions.insert(0, f"Reduce max_model_len from {max_model_len} to {estimated_max_len} or lower")
+        
+        raise InsufficientKVCacheMemoryError(
+            required_kv_memory=needed_memory,
+            available_kv_memory=available_memory,
+            max_model_len=max_model_len,
+            estimated_max_len=estimated_max_len,
+            suggestions=suggestions
+        )
 
 
 def create_kv_cache_group_specs(

vllm/v1/core/kv_cache_utils.py

@@ -0,0 +1,203 @@
+# Enhanced Error Handling for vLLM V1 Initialization
+
+This enhancement provides improved error handling and logging for common initialization errors in vLLM V1, making it easier for users to diagnose and resolve issues.
+
+## Overview
+
+The enhanced error handling addresses the most common initialization problems:
+
+1. **Insufficient GPU Memory** - When the model is too large for available GPU memory
+2. **Insufficient KV Cache Memory** - When there's not enough memory for the KV cache given the max_model_len
+3. **Model Loading Errors** - When model files can't be loaded or are incompatible
+4. **CUDA Errors** - When CUDA-related issues occur during initialization
+
+## Key Features
+
+### 1. Detailed Error Messages
+Instead of generic error messages, users now get:
+- Clear descriptions of what went wrong
+- Specific memory requirements vs. available memory
+- Estimated maximum model lengths based on available memory
+- Context about where the error occurred (model loading, KV cache, etc.)
+
+### 2. Actionable Suggestions
+Each error provides specific suggestions like:
+- Adjusting `gpu_memory_utilization`
+- Reducing `max_model_len`
+- Using quantization (GPTQ, AWQ, FP8)
+- Enabling tensor parallelism
+- Closing other GPU processes
+
+### 3. Enhanced Logging
+- Detailed initialization information logged at startup
+- Memory usage statistics
+- Model configuration details
+- Progress indicators for different initialization phases
+
+### 4. Critical Safety Improvements
+- **ZeroDivisionError Prevention**: Safely handles edge cases where memory profiling returns zero values, preventing uncaught exceptions during initialization
+- **Input Validation**: All error classes validate input parameters (no negative memory values, positive model lengths)
+- **Graceful Error Messaging**: Instead of cryptic crashes, users receive clear explanations of configuration issues
+- **Robust Error Recovery**: Handles unusual memory profiling results that could occur with certain models or test configurations
+
+## New Error Classes
+
+### `InsufficientMemoryError`
+Raised when there's not enough GPU memory to load the model.
+
+```python
+InsufficientMemoryError: Insufficient GPU memory to load the model.
+Required: 24.50 GiB
+Available: 22.30 GiB
+Shortage: 2.20 GiB
+
+Suggestions to resolve this issue:
+  1. Try increasing gpu_memory_utilization first (safest option)
+  2. Increase gpu_memory_utilization from 0.80 (e.g., to 0.90)
+  3. Consider using quantization (GPTQ, AWQ, FP8) to reduce model memory usage
+  4. Use tensor parallelism to distribute the model across multiple GPUs
+  5. Close other GPU processes to free up memory
+```
+
+### `InsufficientKVCacheMemoryError`
+Raised when there's not enough memory for the KV cache.
+
+```python
+InsufficientKVCacheMemoryError: Insufficient memory for KV cache to serve requests.
+Required KV cache memory: 8.45 GiB (for max_model_len=4096)
+Available KV cache memory: 6.20 GiB
+Shortage: 2.25 GiB
+Based on available memory, estimated maximum model length: 3000
+
+Suggestions to resolve this issue:
+  1. Reduce max_model_len from 4096 to 3000 or lower
+  2. Reduce max_model_len from 4096 to a smaller value
+  3. Increase gpu_memory_utilization from 0.80 (e.g., to 0.90)
+  4. Consider using quantization (GPTQ, AWQ, FP8) to reduce memory usage
+  5. Use tensor parallelism to distribute the model across multiple GPUs
+```
+
+### `ModelLoadingError`
+Raised when model loading fails for various reasons.
+
+```python
+ModelLoadingError: Failed to load model 'meta-llama/Llama-3.1-8B' during initialization.
+Error details: CUDA out of memory. Tried to allocate 2.50 GiB
+
+Suggestions to resolve this issue:
+  1. The model is too large for available GPU memory
+  2. Consider using a smaller model or quantization
+  3. Try tensor parallelism to distribute the model across multiple GPUs
+  4. Reduce gpu_memory_utilization to leave more memory for CUDA operations
+```
+
+## Implementation Details
+
+### Files Modified/Added
+
+1. **`vllm/v1/engine/initialization_errors.py`** (NEW)
+   - Contains the new error classes and utility functions
+   - Provides suggestion generation based on error context
+   - Includes detailed logging functions
+
+2. **`vllm/v1/engine/core.py`** (ENHANCED)
+   - Enhanced `_initialize_kv_caches()` method with better error handling
+   - Detailed logging of initialization progress
+   - Proper exception handling with enhanced error messages
+
+3. **`vllm/v1/core/kv_cache_utils.py`** (ENHANCED)
+   - Updated `check_enough_kv_cache_memory()` to use new error classes
+   - Better error messages with specific suggestions
+
+4. **`vllm/v1/worker/gpu_worker.py`** (ENHANCED)
+   - Enhanced memory checking in `init_device()`
+   - Better error handling in `load_model()` and `determine_available_memory()`
+   - More detailed memory profiling error handling
+
+5. **`vllm/v1/engine/llm_engine.py`** (ENHANCED)
+   - Enhanced `__init__()` method with comprehensive error handling
+   - Better error messages for tokenizer and processor initialization
+
+### Error Handling Strategy
+
+The enhancement follows a layered approach:
+
+1. **Low-level functions** (workers, memory profiling) catch specific errors and provide context
+2. **Mid-level functions** (core engine, KV cache utils) add domain-specific suggestions
+3. **High-level functions** (LLM engine) provide user-friendly error aggregation
+
+Each layer adds value while preserving the original error context through exception chaining.
+
+## Usage Examples
+
+### Basic Usage
+```python
+import os
+os.environ["VLLM_USE_V1"] = "1"
+
+from vllm import LLM
+
+try:
+    llm = LLM(
+        model="meta-llama/Llama-3.1-70B-Instruct",
+        gpu_memory_utilization=0.95,
+        max_model_len=8192
+    )
+except Exception as e:
+    print(f"Initialization failed: {e}")
+    # Error message will include specific suggestions
+```
+
+### Advanced Error Handling
+```python
+from vllm.v1.engine.initialization_errors import (
+    InsufficientMemoryError,
+    InsufficientKVCacheMemoryError, 
+    ModelLoadingError
+)
+
+try:
+    llm = LLM(model="large-model", gpu_memory_utilization=0.9)
+except InsufficientMemoryError as e:
+    print(f"Memory issue: {e}")
+    # Handle memory-specific errors
+except InsufficientKVCacheMemoryError as e:
+    print(f"KV cache issue: {e}")
+    # Handle KV cache-specific errors
+except ModelLoadingError as e:
+    print(f"Model loading issue: {e}")
+    # Handle model loading errors
+```
+
+## Testing
+
+Run the demo script to see the enhanced error handling in action:
+
+```bash
+python enhanced_error_demo.py
+```
+
+This script intentionally triggers various error conditions to demonstrate the improved error messages and suggestions.
+
+## Benefits
+
+1. **Faster Debugging** - Users can quickly understand what went wrong
+2. **Self-Service Resolution** - Clear suggestions help users fix issues independently
+3. **Better Support Experience** - More detailed error reports improve support quality
+4. **Reduced Trial-and-Error** - Specific suggestions reduce the need for guesswork
+
+## Backward Compatibility
+
+The enhancement is fully backward compatible:
+- Existing error handling code continues to work
+- New error classes inherit from standard Python exceptions
+- Original error messages are preserved in the error chain
+- No breaking changes to existing APIs
+
+## Future Enhancements
+
+Potential areas for further improvement:
+1. Add error handling for distributed setup issues
+2. Enhanced logging for multimodal model initialization
+3. Better error messages for quantization setup
+4. Integration with monitoring/telemetry systems