Fix "SentenceTransformer model download failed"

You call SentenceTransformer("all-MiniLM-L6-v2") and instead of a model you get one of these:

OSError: We couldn't connect to 'https://huggingface.co' to load this file
requests.exceptions.ConnectionError: HTTPSConnectionPool(...): Max retries exceeded
requests.exceptions.SSLError: certificate verify failed
huggingface_hub.utils._errors.HfHubHTTPError: 401 Client Error: Unauthorized

Here's the trap: people search the exact string, find one fix, try it, and it doesn't work — because "download failed" isn't one error. It's the visible end of several very different failures: a wrong name, a gated model, a blocked network, a slow link, or a corrupted cache. The fix depends entirely on which one you have.

This guide maps each symptom to its cause and fix, with special attention to the two that generate the most support tickets: corporate SSL/proxy errors and the cached_download version mismatch that masquerades as a download problem.

Quick Answer

Match the symptom to the fix. Wrong name → 404, correct the id. Gated model → 401, authenticate. Network/SSL/proxy → set HTTPS_PROXY and REQUESTS_CA_BUNDLE, or use an HF_ENDPOINT mirror. Timeout/partial → raise HF_HUB_DOWNLOAD_TIMEOUT and re-run to resume. Corrupted cache/full disk → clear the cache and force_download=True.

TL;DR

• It's a class of errors — read the real exception, then triage.
• 404 → wrong model name. 401 → gated, authenticate.
• SSL/proxy (corporate) → HTTPS_PROXY + REQUESTS_CA_BUNDLE, or HF_ENDPOINT.
• Timeout/partial → HF_HUB_DOWNLOAD_TIMEOUT, re-run (resumes automatically).
• Corrupted cache → clear it + force_download=True.
• ImportError: cached_download → version mismatch; upgrade both libraries.
• Air-gapped → pre-download, copy the cache, HF_HUB_OFFLINE=1.

Where It Actually Fails

Loading a SentenceTransformer runs four stages, and each one fails in its own way:

1. Resolve the repo id — a bad name (or missing sentence-transformers/ prefix) → 404.
2. Authenticate — a gated or private model without a token → 401/403.
3. Download over HTTPS — no route, a proxy, or a bad certificate → connection/SSL error.
4. Write to the cache — a corrupted partial file or a full disk → an OSError.

Read the traceback to see which stage you're in, then jump to that fix below.

The Triage

Step-by-step Solution

Symptom 1: 404 — wrong model name

SentenceTransformers prepends sentence-transformers/ to bare names, but only for its own models. If the name is wrong or in another namespace, you get a "not found":

from sentence_transformers import SentenceTransformer
 
# ❌ typo / wrong namespace
SentenceTransformer("all-MiniLM-L6")          # not a real id → 404
 
# ✅ exact id
SentenceTransformer("all-MiniLM-L6-v2")       # resolves to sentence-transformers/all-MiniLM-L6-v2
SentenceTransformer("BAAI/bge-small-en-v1.5") # full namespace for third-party models

Copy the id from the model's Hub page rather than typing it. A "Repository Not Found" can also mean a private repo you can't see — see Hugging Face 401 Unauthorized.

Symptom 2: 401 — gated model

Some embedding models are gated. A 401 here is authentication, not network. Authenticate and accept the terms:

huggingface-cli login          # or: export HF_TOKEN=hf_xxx

The full gated-access flow (accept terms + token scope, including the fine-grained-token gotcha) is covered in the 401 guide.

Symptom 3: SSL / proxy error (the corporate-network case)

On a company network this is the most common failure. The download is blocked or intercepted by a proxy with its own certificate. Point the HTTP stack at the proxy and your organization's CA:

export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export REQUESTS_CA_BUNDLE="/etc/ssl/certs/company-ca.pem"   # your org's CA bundle

If Hugging Face itself is blocked in your region or network, route through an approved mirror instead:

export HF_ENDPOINT="https://hf-mirror.com"   # example mirror; use one your org approves

Symptom 4: Timeout / partial download

Large models on a slow link time out mid-download. Give it more time and let it resume:

export HF_HUB_DOWNLOAD_TIMEOUT=60      # seconds per request (default is lower)

huggingface_hub resumes partial downloads on re-run automatically, so just run the script again after raising the timeout. For repeatable environments, pre-download once and load from cache.

Symptom 5: Corrupted cache or full disk

An interrupted download can leave a broken file that fails every subsequent load. Force a clean re-download, or clear the cache:

from sentence_transformers import SentenceTransformer
 
# Force a clean re-download of this model
model = SentenceTransformer("all-MiniLM-L6-v2", cache_folder=None)
# under the hood you can also pass force_download via huggingface_hub:

# Or clear the model's cache folder and retry
rm -rf ~/.cache/huggingface/hub/models--sentence-transformers--all-MiniLM-L6-v2
df -h ~/.cache          # confirm you actually have free disk space

• A full disk is a surprisingly common cause — embedding models plus their cache can be gigabytes.
• After clearing, the next load re-downloads cleanly.

Symptom 6: ImportError: cannot import name 'cached_download'

This one looks like a download failure but is a dependency conflict. A newer huggingface_hub removed cached_download, which older sentence-transformers still imports. Upgrade both together:

pip install -U sentence-transformers huggingface_hub

Pinning only one of them is what causes this — keep them compatible.

Offline & Air-Gapped Environments

For servers with no internet, download once where you have access, then go offline:

# 1) On a connected machine:
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
model.save("/models/all-MiniLM-L6-v2")     # writes a self-contained folder

# 2) Copy /models/all-MiniLM-L6-v2 to the air-gapped machine, then:
export HF_HUB_OFFLINE=1                     # never touch the network

# 3) Load from the local path — no download attempted:
model = SentenceTransformer("/models/all-MiniLM-L6-v2")

HF_HUB_OFFLINE=1 makes the library fail fast instead of hanging on a network it can't reach.

Platform-Specific Notes

Docker

• Pre-download during the build so runtime needs no network: RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')".
• Pass HTTPS_PROXY, REQUESTS_CA_BUNDLE, and HF_TOKEN into the build/run if needed.
• Mount a shared cache volume so replicas don't each re-download.

Windows

You may see a symlink warning the first time. Downloads still work (as copies). Silence it or enable Developer Mode:

set HF_HUB_DISABLE_SYMLINKS_WARNING=1

CI/CD

Cache ~/.cache/huggingface between runs so every job doesn't re-download, and set HF_TOKEN as a secret for gated models. A cold cache plus a slow runner is a frequent timeout cause.

Verification Steps

1. The model loads and encodes:

from sentence_transformers import SentenceTransformer
m = SentenceTransformer("all-MiniLM-L6-v2")
print(m.encode("hello").shape)   # (384,) — download + load succeeded

2. The cache folder exists and has files under ~/.cache/huggingface/hub/models--sentence-transformers--all-MiniLM-L6-v2.
3. On a restricted network, the download completes with your proxy/CA set — no SSLError.
4. In offline mode, loading from the local path works with HF_HUB_OFFLINE=1.
5. df -h shows free disk space after the download.

Prevention

• Copy model ids from the Hub page; don't type them.
• Set proxy and CA variables once in your shell profile or CI config.
• Pre-download models in Docker builds and cache them in CI.
• Keep sentence-transformers and huggingface_hub upgraded together.
• Set HF_HUB_DOWNLOAD_TIMEOUT higher on known-slow networks.
• For air-gapped deploys, ship the model folder and set HF_HUB_OFFLINE=1.
• Monitor disk space where the cache lives.

Troubleshooting Matrix

Related Guides

• Resolve Hugging Face 401 Unauthorized
• Resolve OSError: Can't load tokenizer
• Fix OpenAI RateLimitError (429)
• Resolve ChromaDB collection does not exist
• Building offline-first ML deployments

External References

• SentenceTransformers documentation
• Hugging Face Hub — Download files
• Hugging Face Hub — Environment variables
• requests — SSL/proxy configuration

FAQs

Is model.save() the same as the Hub cache? No. model.save(path) writes a self-contained folder you control — ideal for shipping to offline machines. The Hub cache under ~/.cache/huggingface is managed automatically and keyed by repo id. Either works for loading; save() gives you an explicit, portable copy.

Why does it work locally but fail on the server? Almost always network: the server sits behind a proxy or firewall, or has no outbound internet. Set the proxy/CA variables, or pre-cache the model and use offline mode. It's rarely the code.

Can I speed up large downloads? Enable the faster transfer backend with pip install hf_transfer and HF_HUB_ENABLE_HF_TRANSFER=1. It parallelizes chunks and helps most on high-bandwidth links.

Does clearing the cache lose my other models? Only if you delete the whole hub folder. Delete the specific models--namespace--name subfolder to clear just one model and keep the rest.

The download restarts from zero every time — why? That points at a cache the process can't persist (a fresh container each run, or a read-only cache dir). Mount a writable, persistent cache volume so resume works.