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.

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”