ComfyUI HuggingFace HttpRequestException: Fix Hugging Face Model Download Failures

If ComfyUI or a launcher reports HuggingFace HttpRequestException during a model download, do not reinstall ComfyUI first.

The error usually means the downloader could not complete a request to Hugging Face, or Hugging Face rejected the request because the repo is gated, private, renamed, or missing. Your Python environment may still be fine.

Quick Diagnosis

Evidence from Real ComfyUI Failures

In the local Wonderful Launcher issue data, download_failed with HttpRequestException appeared across multiple stable app versions and was grouped under model_asset_loading.

The ComfyUI issue dataset shows the same family of failures in different wording:

• MaxRetryError and SSL failures while downloading from huggingface.co
• Cannot connect to host huggingface.co:443
• LocalEntryNotFoundError when the file is not in the local cache and the Hub cannot be reached
• HfHubHTTPError / unauthorized responses when a node tries to download from a gated or private repo
• requests for mirror support or offline installation when large model downloads are unreliable

That is why this page treats the error as a download-path diagnosis first, not a "broken ComfyUI install" diagnosis.

Step 1: Test the Exact Hugging Face URL Outside ComfyUI

First find the URL or repo name in the log. It may look like one of these:

https://huggingface.co/owner/repo/resolve/main/model.safetensors
owner/repo

Open it in a browser on the same machine. Then test it from the terminal:

Invoke-WebRequest -Uri "https://huggingface.co" -UseBasicParsing -TimeoutSec 20

For a specific file, use a HEAD request so you do not download a multi-gigabyte model just to test connectivity:

curl.exe -L -I "https://huggingface.co/owner/repo/resolve/main/model.safetensors"

Interpret the result:

Step 2: Separate Network Errors from Permission Errors

Hugging Face's huggingface_hub library refines HTTP failures into errors such as RepositoryNotFoundError, GatedRepoError, RevisionNotFoundError, EntryNotFoundError, and HfHubHTTPError.

For ComfyUI users, the practical split is:

Do not solve 403 or gated-model errors by changing CUDA, Torch, or random Python packages. Those are access problems.

Step 3: Configure Proxy Before Launching ComfyUI

If your browser can reach Hugging Face only through a proxy, make sure the ComfyUI process also gets that proxy.

For a temporary PowerShell session:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
python main.py

For a Windows portable .bat file, add the proxy before the embedded Python command:

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build
pause

Replace 7890 with the actual port used by your proxy tool.

If ComfyUI is launched by a desktop app, launcher, service, scheduled task, or terminal shortcut, set the proxy in the place that launches ComfyUI. Setting it in a different terminal window will not help the already-running process.

Step 4: Check Token and Gated Model Access

Some workflows and custom nodes download models from gated or private Hugging Face repos. In that case, a public browser URL may not be enough.

Check these in order:

1. Open the Hugging Face repo page while logged in.
2. Accept the model license or access request if the repo is gated.
3. Create or use a token with permission to read that repo.
4. Pass the token to the same process that launches ComfyUI.

For a temporary PowerShell session:

$env:HF_TOKEN = "hf_your_token_here"
python main.py

To confirm the active Python can see the token:

python -c "import os; print('HF_TOKEN set:', bool(os.environ.get('HF_TOKEN')))"

To confirm the active Python can authenticate through huggingface_hub:

python -c "import os; from huggingface_hub import HfApi; print(HfApi(token=os.environ['HF_TOKEN']).whoami()['name'])"

If that command fails with an auth error, fix the token or account access before changing ComfyUI.

Step 5: Check Offline Mode and Hugging Face Cache

Hugging Face supports cache and offline behavior through environment variables such as HF_HOME, HF_HUB_CACHE, HF_TOKEN, and HF_HUB_OFFLINE.

Check what the active process sees:

python -c "import os; print('HF_HOME=', os.environ.get('HF_HOME')); print('HF_HUB_CACHE=', os.environ.get('HF_HUB_CACHE')); print('HF_HUB_OFFLINE=', os.environ.get('HF_HUB_OFFLINE'))"

If HF_HUB_OFFLINE=1, Hub requests will fail unless the file is already cached. This can look like a download bug when the real issue is offline mode plus an empty cache.

Be careful with the cache:

• Do not edit files inside the Hugging Face cache manually.
• Do not delete the whole cache if you have many large models already downloaded.
• If one download was interrupted, remove only the partial file or redownload to a clean location.

Step 6: Use Manual Download Only When It Matches the Node

Manual download is a good fallback for normal model files such as .safetensors, .gguf, .pth, .bin, or .onnx.

Use this pattern:

1. Download the file in a browser or download manager.
2. Verify the file size is complete.
3. Put it in the correct ComfyUI folder.
4. Restart ComfyUI or refresh the model dropdown.

Common destinations:

For the full folder map, use Where to Put Safetensors in ComfyUI.

Some custom nodes do not look in normal ComfyUI model folders. They may call hf_hub_download() and expect the file in the Hugging Face cache or in a node-specific folder. If manual placement does not work, read the node README before moving files around.

Step 7: Avoid Package Drift While Fixing Downloads

Do not start by reinstalling torch, transformers, or huggingface_hub unless the error clearly says an import or version requirement failed.

These are different problems:

The safest order is:

1. Preserve the working environment.
2. Test the URL.
3. Fix proxy/token/cache.
4. Redownload or move only the missing model file.
5. Change packages only when the log proves it is a package issue.

How Wonderful Launcher Helps

Wonderful Launcher is useful when model downloads are mixed with environment risk:

• it keeps logs tied to the specific package you launched
• it helps preserve existing models and workflows before repair
• it lets you separate stable and experimental ComfyUI packages
• it reduces the temptation to run random pip install commands in the wrong Python environment

If the file URL works but ComfyUI still cannot download or locate the model, use the launcher logs to capture the exact URL, target path, Python environment, and error family before changing dependencies.

Related Guides

• Download Models
• Where to Put Safetensors in ComfyUI
• ComfyUI Failed to Get Custom Node List
• ComfyUI Dependency Conflicts
• How to Fix ComfyUI Plugin Import Failed Errors
• Deployment Failed: Downloading the Resource Package

Source References

• Hugging Face Hub file download guide
• Hugging Face Hub file download API
• Hugging Face Hub environment variables
• Hugging Face Hub HTTP error utilities
• ComfyUI issue: connection issue downloading models from Huggingface
• ComfyUI issue: cannot connect to host huggingface.co
• ComfyUI issue: MaxRetryError downloading from huggingface.co
• ComfyUI issue: LocalEntryNotFoundError cache miss