Learn AI Create the Future — with Pranay
Main site

Error database

OSError: We couldn't connect to huggingface.co (offline / cache errors)

The download from the Hugging Face Hub failed — network, proxy, an outage, or an accidental offline flag. Retry, check the proxy, or pre-download once and run from cache.

The message you saw
OSError: We couldn't connect to huggingface.co (offline / cache errors)

By Updated

The error

Output
OSError: We couldn't connect to 'https://huggingface.co' to load this file, couldn't find it in the cached files and it looks like mistralai/Mistral-7B-Instruct-v0.3 is not the path to a directory containing a file named config.json.
Checkout your internet connection or see how to run the library in offline mode at 'https://huggingface.co/docs/transformers/installation#offline-mode'.

A sibling appears when only the cache is allowed:

Output
huggingface_hub.errors.LocalEntryNotFoundError: An error happened while trying to locate the file on the Hub and we cannot find the requested files in the local cache.

What it means

from_pretrained tried the network, failed, then tried the local cache, and failed there too. The message bundles three distinct possibilities — no connectivity, a Hub outage, or a repo id that does not exist as either a Hub model or a local folder. Which one you have determines the fix, so diagnose before changing code.

Why it happens

Ordinary network trouble covers most cases: no internet, a corporate proxy or firewall that blocks or intercepts huggingface.co, DNS failures inside containers. Hub outages happen occasionally. Self-inflicted versions: the HF_HUB_OFFLINE=1 environment variable left set from an experiment, a typo in the repo id, or a moved cache directory (HF_HOME pointing somewhere empty).

How to fix it

1. Separate outage from local problem. Open huggingface.co in a browser, and check status.huggingface.co. If the Hub is down, wait — nothing on your machine is wrong.

2. Check for a leftover offline flag.

bash
env | grep -i HF_

If HF_HUB_OFFLINE=1 or TRANSFORMERS_OFFLINE=1 shows up unexpectedly, unset it.

3. Behind a corporate proxy, set the proxy variables — and the CA bundle.

bash
export HTTPS_PROXY=http://proxy.company.com:8080
export REQUESTS_CA_BUNDLE=/path/to/company-root-ca.pem

TLS-inspecting proxies need the second line, or the failure shows up as SSL errors — see the related SSL page.

4. Verify the repo id is real. Copy it from the model page URL, exactly. A typo produces this same message because the fallback "maybe it is a local directory" also fails.

5. For flaky networks and servers, pre-download once, then run from cache.

bash
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3

The files land in the standard cache (~/.cache/huggingface unless HF_HOME says otherwise). After that, loads are local. For air-gapped or reproducible runs, make it explicit:

python
model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-Instruct-v0.3", local_files_only=True
)

local_files_only=True also removes startup network checks from production services that should never surprise-download.

How to prevent it

Bake model downloads into setup (a one-time huggingface-cli download step), not into serving. Set HF_HOME deliberately on machines with small home directories, and document it. In CI and Docker builds, cache the model layer so every build does not re-download gigabytes.