ValueError
vllm.LLMError: Model not found on Huggingface Hub
Stack trace
ValueError: Model 'nonexistent-model-id' not found on Huggingface Hub.
File "app.py", line 12, in <module>
llm = LLM(model='nonexistent-model-id') # triggers error
File "vllm/llm.py", line 45, in __init__
raise ValueError(f"Model '{model}' not found on Huggingface Hub.") Why it happens
This error occurs because vLLM tries to load a model from the Huggingface Hub using the provided model ID, but the ID does not exist or is misspelled. The Huggingface Hub cannot find the model repository, causing vLLM to raise a ValueError.
Detection
Check for ValueError exceptions during LLM initialization and verify the model ID string before runtime to catch typos or missing models early.
Causes & fixes
Incorrect or misspelled Huggingface model ID passed to vLLM
Verify the exact model ID on the Huggingface Hub website and update your code to use the correct model identifier.
Model repository is private or deleted on Huggingface Hub
Ensure you have access permissions or choose a public model. If private, authenticate with Huggingface CLI or provide a token.
No internet connection or network issues preventing access to Huggingface Hub
Check your network connectivity and proxy settings to allow access to the Huggingface Hub.
Code: broken vs fixed
from vllm import LLM
llm = LLM(model='nonexistent-model-id') # triggers ValueError: model not found
print(llm.generate('Hello'))import os
from vllm import LLM
# Use environment variable for model ID and set a valid Huggingface model
model_id = os.environ.get('VLLM_MODEL_ID', 'facebook/opt-1.3b')
llm = LLM(model=model_id) # fixed: valid model ID
print(llm.generate('Hello'))Workaround
Catch the ValueError during LLM initialization, log the invalid model ID, and fallback to a default known-good model ID programmatically.
Prevention
Always validate model IDs against the Huggingface Hub before deployment and use environment variables to manage model configuration securely.