
Fix Hugging Face Download Timeouts and IncompleteRead on Linux
A failed model download can leave several plausible causes: an interrupted connection, an inaccessible repository, exhausted storage, or a mismatch between a tutorial and the installed Hub client. Preserve the existing cache while you identify the failure. Deleting it first can discard usable files and remove evidence about what was downloaded.
The guidance below distinguishes the v1.0 migration described by Hugging Face from behavior in the supplied current documentation. The documentation excerpts are dynamic; check the documentation and help for your pinned installation before applying an option.
Start with the failure, not a tuning flag
Use this decision tree before retrying:
- Is there an HTTP status? Investigate 401/403 as an access problem, 429 as a rate-limit problem, and 5xx as a possible service-side failure. Preserve the status and request context without recording credentials.
- Is the error a timeout, reset, or
IncompleteRead? Check the network route and proxy, then consider a bounded retry. The exception alone does not identify which component dropped the connection. - Did a write fail or storage fill up? Check free space, quotas, permissions, and the actual cache and destination filesystems. Resolve the local problem before retrying.
- Does the client reject an argument or fail to start? Identify the executable and Python environment used by the job, then consult help and documentation for that installed release.
Record the package and Python versions, repository identifier, requested revision, destination, timestamp, and sanitized error. If the download is run by a service or scheduler, inspect its environment: an interactive shell may use a different executable, cache location, proxy, or account.
Establish the version and transfer path
For an application that depends on huggingface_hub, inspect its lockfile or environment and downstream requirements before changing versions. The v1.0 migration guide says v1.0 requires Python 3.9 or newer and changed HTTP handling from requests to httpx. Code that catches only requests exceptions or configures an older HTTP backend therefore needs review during migration.
The guide also states that v1.0 no longer supports per-method proxy configuration: configure HTTP_PROXY and HTTPS_PROXY globally for that client version instead. Treat proxy settings as sensitive operational configuration, and avoid copying credential-bearing proxy URLs into logs or tickets.
Xet is the default transfer path where applicable in current Hub configurations, but it is not an assumption to make about every job. hf-xet can be disabled, and installation availability or configuration can change the path. Inspect the actual environment and the documentation for the installed releases of both packages before diagnosing Xet-specific behavior. A Hub major version alone does not prove which path a particular transfer used.
Prepare a safe retry
Before restarting a large download:
- Verify the repository identifier, repository type, required access approval, and account permissions using the intended identity. Confirm the repository and revision are accessible; an example identifier in a tutorial is not evidence of access.
- Pin the intended revision for reproducibility. The download guide documents revisions for file and repository downloads; when using a commit hash with
hf_hub_download, it specifies the full-length hash. - Check capacity and write permissions on both the Hub cache and any separate destination. The environment reference distinguishes the Hub repository cache from the Xet shard cache; they may have different storage implications.
- Keep existing cache files intact. Retry through the same supported client and inspect its result; reuse or recovery of a partial download depends on the installed version and state. Do not assume every interrupted transfer resumes at a particular byte.
- Confirm completion against the intended revision and expected file inventory before starting a serving or training job. Where trusted checksums are available for that revision, verify them using the provider’s documented procedure.
The download guide says hf_hub_download returns a path into a version-aware cache and warns against modifying that file, since doing so can corrupt the cache. If an application needs mutable files, arrange a separate working copy according to its deployment procedure.
Choose CLI or Python with the pinned release
The supplied CLI reference identifies hf download as a download command and documents top-level help. It does not, in the supplied excerpt, establish the exact download options for a particular installed release. Before constructing an invocation, inspect that release’s hf download help and matching official reference for repository type, revision, destination, concurrency, and authentication options. Verify the selected repository separately.
For an integrated Python workflow, the supplied download guide describes hf_hub_download for a single file and snapshot_download for a repository at a revision. It says snapshot downloads use concurrent file downloads and the local cache. Check the pinned release’s function signature and reference before choosing additional arguments or retry behavior; the excerpt does not establish a particular worker-count argument.
Download and validate artifacts before allocating scarce serving resources where the application’s architecture permits it. Wrap transient failures in bounded retries with backoff, a limit, and useful error reporting. A retry loop should surface persistent failures rather than keep a deployment waiting indefinitely.
Adjust timeouts only for the observed failure
The current environment-variable reference distinguishes two settings:
HF_HUB_ETAG_TIMEOUTcontrols how long to wait for repository metadata. On timeout, the documented behavior is to fall back to locally cached files. That can be useful offline or on a slow connection, but it also means an operator requiring a particular revision must verify what was obtained.HF_HUB_DOWNLOAD_TIMEOUTcontrols the wait for a server response while downloading; the reference says a timeout raisesTimeoutError.
A longer wait may help a slow response, but it cannot repair denied access, full storage, or a broken route. Check the exact semantics and defaults for the pinned release, set a change for the affected job, and observe whether the failure changes. The current reference says Hub environment variables are read at import time, so set them before the Python process imports huggingface_hub; changing them afterward will not affect that import.
Avoid applying old throughput recipes blindly. The supplied current reference says HF_XET_NUM_CONCURRENT_RANGE_GETS is no longer used and that download concurrency has been adaptive since hf_xet 1.3.0. It also says HF_XET_CHUNK_CACHE_SIZE_BYTES no longer enables a download chunk cache. Check your installed version’s documentation before using either older guidance or current guidance for a different release.
Respond to the failure class
| Failure | Investigation and next action |
|---|---|
| 401 or 403 | Check the active identity, token permissions, and any repository access requirements. Correct access before retrying; do not put tokens in commands, logs, or shared tickets. |
| 429 | Respect any server-provided retry guidance and use bounded backoff. Reduce repeated requests if the workload is causing pressure. |
| 5xx, reset, or incomplete read | Save sanitized diagnostics, check proxy and network behavior, and retry with a limit. Escalate persistent failures with the error and timing evidence. |
| Metadata timeout | Check connectivity and whether a cached result is acceptable for the required revision. Do not assume cached metadata is fresh. |
| Disk or permission error | Check the cache and destination mounts, quotas, and service identity. Free space or correct permissions without deleting unrelated data. |
| Unrecognized option | Stop and match the executable, package version, and release-specific help. Do not combine flags from different tutorials. |
Primary sources
- Hugging Face Hub v1.0 migration guide — Python requirement, HTTP client migration, proxy configuration, and error-handling changes.
- Hub environment-variable reference — cache locations, timeout semantics, import timing, and current Xet variable notes.
- Hub download guide — cache behavior, file and snapshot downloads, and revisions.
- Hub CLI reference — CLI command overview and help.
Validation boundary: No command, download, repository access, or configuration in this article has been executed or verified against a specific installed release. The supplied source excerpts were reviewed for this correction on November 13, 2026; dynamic documentation does not establish when every current behavior existed. Verify release-specific documentation and your own environment before production use.