Hugging Face "ConnectionError: Couldn't reach huggingface.co" in CI

transformers or datasets tried to reach huggingface.co and the connection failed: no network egress, DNS failure, or a transient outage. If the assets are already cached you can run fully offline with HF_HUB_OFFLINE=1.

What this error means

A load fails with "ConnectionError: Couldn't reach 'https://huggingface.co'" or "We couldn't connect to https://huggingface.co to load this file", sometimes after a long hang.

huggingface_hub

requests.exceptions.ConnectionError: Couldn't reach https://huggingface.co
(error 000) - retrying...
ValueError: Connection error, and we cannot find the requested files in the cached path.

Common causes

The runner has no egress to huggingface.co

A locked-down network, proxy, or DNS failure blocks the Hub, so every metadata and file request fails.

A transient Hub or network outage

A brief outage or packet loss drops the connection mid-request; it usually clears on retry.

How to fix it

Run offline against a warm cache

Pre-populate HF_HOME (cache it between runs) and set offline mode so no network call is attempted.

.github/workflows/ci.yml

env:
  HF_HOME: ${{ github.workspace }}/.hf-cache
  HF_HUB_OFFLINE: '1'
  TRANSFORMERS_OFFLINE: '1'

Allow egress or configure the proxy

If the job must fetch, allow outbound HTTPS to huggingface.co and set HTTPS_PROXY when a proxy is required.

Terminal

export HTTPS_PROXY=http://proxy.internal:3128
python -c "from huggingface_hub import model_info; model_info('bert-base-uncased')"

How to prevent it

Cache HF_HOME between runs so offline mode has the assets it needs.
Set HF_HUB_OFFLINE=1 for reproducible, network-free jobs.
Allowlist huggingface.co egress when downloads are required.