Hugging Face "Couldn't connect to huggingface.co" in CI

transformers/datasets tried to fetch from the Hub and the network request failed. The cause is a flaky or blocked connection, a Hub outage, or a runner with no outbound internet - not a bad model id.

What this error means

A load fails with "ConnectionError: Couldn't reach 'X' on the Hub (...)" or "We couldn't connect to 'https://huggingface.co' to load this file". It often passes on retry.

python

requests.exceptions.ConnectionError: Couldn't connect to 'https://huggingface.co' to
load this model, couldn't find it in the cached files ...

Common causes

Transient network failure or Hub rate limiting

A momentary DNS/TLS failure or a slow Hub response drops the request; a retry usually succeeds.

A runner with restricted or no egress

Locked-down CI networks block huggingface.co, so the fetch fails unless artifacts are pre-cached.

How to fix it

Pre-cache models and run offline

Download artifacts in a setup step (or restore them from cache), then set offline mode so the test never hits the network.

Terminal

export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1

Cache the Hub directory between runs

Persist ~/.cache/huggingface so models fetched once are reused and a flaky network does not refetch.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/huggingface
    key: hf-${{ hashFiles('requirements.txt') }}

How to prevent it

Cache the Hugging Face cache directory across CI runs.
Pin model revisions and pre-download them in a setup step.
Use offline mode in tests once artifacts are cached.