Skip to content
Docs

Troubleshooting — Downloads

It fails with model_download_failed

Section titled “It fails with model_download_failed”

Almost always a gated or private repository, which fails in a way that looks like a network problem.

  1. Add a token: HuggingFace Tokens → Add Token.
  2. Accept the model’s licence on the hub with the same account. This is the step that gets skipped, and it produces the identical error to having no token.
  3. Check the token was not revoked on the hub — the stored copy cannot know.

See Hugging Face tokens.

It is refused before I can click Download

Section titled “It is refused before I can click Download”

The repository holds only full-precision weights and this machine has no tensor engine — every Mac, and any Linux machine without CUDA or ROCm.

Choose a GGUF build of the same model. A repository holding both formats is not blocked; its GGUF variants are still offered.

This is deliberate: a 60 GB download that could never load is worth preventing. See Model formats.

It failed with format_not_servable

Section titled “It failed with format_not_servable”

The same check, running server-side on a path the picker could not judge in advance. Same remedy.

It pulled far more than I expected

Section titled “It pulled far more than I expected”

The variant picker was bypassed. A GGUF repository often holds twenty quantizations; tick one.

The Download button starts disabled and enables only once the listing has resolved and a variant is ticked — precisely to prevent this. If you saw a warning panel and an enabled button, the listing could not be read and you proceeded with a whole-repository download. See GGUF variants.

model_too_large or remote_disk_full

Section titled “model_too_large or remote_disk_full”

Disk in the models directory, locally or on the node being replicated to. Free space or point at a larger volume.

model_not_present_on_node

Section titled “model_not_present_on_node”

A remote server was asked to serve weights that node does not have. Replication is explicit — start the download again choosing that node.

A download seems stuck

Section titled “A download seems stuck”

Progress reflects real byte and file totals, so a stalled figure means a stalled transfer rather than a reporting artefact. Cancel it; the registry entry resets immediately and a corrected download can be queued straight away.

It stalls at zero bytes, or fails with CAS Client Error

Section titled “It stalls at zero bytes, or fails with CAS Client Error”

The error names a CDN URL rather than an action, and looks like this:

Task error: File reconstruction error: CAS Client Error: Request middleware
error: error sending request for url (https://us.aws.cdn.hf.co/xorbs/...)

This is Xet, Hugging Face’s newer transfer backend. It arrives as hf-xet inside the [hub] extra and is used automatically whenever it is installed. Where it cannot establish its transfer the download either fails with the error above or sits at zero bytes with an .incomplete file that never grows.

Disable it and use the classic HTTP path:

Terminal window
$env:HF_HUB_DISABLE_XET = "1"     # PowerShell
Terminal window
export HF_HUB_DISABLE_XET=1       # macOS, Linux

Restart the control plane so the download thread picks the variable up, then download again.

Before reaching for this, confirm it is not simply the network: the classic path works independently, so curl -r 0-2000000 -o NUL "https://huggingface.co/<repo>/resolve/main/<file>" returning bytes while the console sits at zero is the signal. Measured on Windows 11: two attempts stalled at 0 bytes, and with Xet disabled the same 491 MB file completed at about 2 MB/s.

The model downloaded but the server will not start

Section titled “The model downloaded but the server will not start”

A different problem — see Server will not start. The common overlap is a sharded GGUF, which downloads fine and cannot be served by the tensor engine until merged.

Sources and references

Section titled “Sources and references”