Skip to content
Neutree Documentation

Hugging Face model download hangs

Issue

When the network environment is unstable, downloading models from Hugging Face using huggingface-cli or the integrated hf_hub library may hang.

You may observe the following:

  • The download progress stops and does not resume.
  • No errors are reported, but the process hangs.
  • This issue occurs more frequently in environments with high network latency or high packet loss.

Cause

This is a known issue with the hf_xet component. Hugging Face uses the hf_xet component to improve model download efficiency, but in environments with unstable network connections, Xet downloads may hang indefinitely.

Solution

Set the environment variable HF_HUB_DISABLE_XET=1 when downloading models to disable the Xet protocol and fall back to the standard HTTP protocol. Although this may be slower, it is more reliable in unstable network conditions.

Choose the appropriate solution based on how you download models.

If you encounter this issue when an endpoint is configured with a Hugging Face model repository and automatically pulls open-source models from Hugging Face, follow these steps to resolve it:

  1. Log in to the Neutree management interface, select the target endpoint from the endpoint list, or click the menu icon (…) on the target endpoint’s details page and select Edit.

  2. On the configuration page, click Configuration Details, and add the following environment variable:

    • Key: HF_HUB_DISABLE_XET
    • Value: 1

  3. Click Save to complete the edit.