Model Download Hangs

Problem

When downloading models from HuggingFace using the huggingface-cli or hf_hub library, the download may hang in unstable network environments.

This is a known issue with the hf_xet component (HuggingFace’s accelerated download mechanism). In environments with unstable network connections, xet downloads can become stuck indefinitely.

What you might see:

• Download progress stops and never resumes
• No error message is shown, the process just hangs
• The issue occurs more frequently in environments with high latency or packet loss

Solution

Disable the xet download mechanism and fall back to standard HTTP downloads by setting the following environment variable:

HF_HUB_DISABLE_XET=1

Configuring in Neutree Endpoint

If your endpoint uses a HuggingFace-type model registry and encounters this issue during automatic model download:

1. In the endpoint form, open Custom Settings > Environment Variables
2. Add a new environment variable:
   • Name: HF_HUB_DISABLE_XET
   • Value: 1
3. Save the endpoint

Using with CLI Directly

If you are downloading models manually using the HuggingFace CLI:

export HF_HUB_DISABLE_XET=1
huggingface-cli download meta-llama/Llama-3.1-8B-Instruct --local-dir ./models/llama-3.1-8b

Notes

• This workaround disables the accelerated xet protocol and uses standard HTTP downloads instead, which may be slower but is more reliable in unstable network conditions.
• This is an upstream issue in the xet-core library. For more details, see:
  • xet-core#409
  • xet-core#483